0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35 /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 urce code. In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 al notice, here
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 *.** May you
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 do good and not
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 evil..** May
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65 you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 hers..** May
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79 you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76 ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66 ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20 ile defines the
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74 interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73 client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69 . If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64 on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69 onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41 ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73 PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64 tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63 not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74 ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68 e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66 at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61 ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74 s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74 al". Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 ite. We do not
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67 anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65 but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 inor changes.**
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63 ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 e is derived.**
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 this file. Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66 e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 file makes some
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68 this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73 ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64 art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23 ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48 define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72 .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64 g.h> /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74 ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 */../*.** Make
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 C++..*/.#ifdef
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65 __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20 ../*.** Provide
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20 verride linkage
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20 features of the
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69 interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54 fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72 ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65 QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43 fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54 ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53 DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51 QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65 TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50 def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72 nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20 faces as either
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78 deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 perimental. New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 should not use
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72 deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65 faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 atibility only.
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61 ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74 aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69 d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67 ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61 that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 nd gone back to
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 using simple.**
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 le-Time Library
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70 ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61 .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69 luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 ng literal that
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 rsion in the.**
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77 format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61 here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72 er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64 .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 Y is the minor
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65 nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 cro resolves to
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69 an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59 + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20 , and Z are the
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 same.** numbers
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79 N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20 so.** be larger
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65 than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69 from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68 s derived. Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 er Y will.** be
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20 emented or else
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20 ill be reset to
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65 18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73 source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 been stored in
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 ystem</a>. ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65 D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65 which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20 e.** within its
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 ate and time of
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73 or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 h of the entire
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66 source tree. If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65 the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69 has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73 ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74 ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65 checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73 igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65 h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 LITE_VERSION
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d OURCE_ID "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 un-Time Library
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 TE_SOURCE_ID] C
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f file. ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 s might include
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 atch the macros
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72 , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 ing library and
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65 ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30 ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 ins the text of
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 .** macro. ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ant. The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 tring constants
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 within the DLL.
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c BER]. ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 ite3_sourceid()
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 ant whose value
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20 rocessor macro.
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74 Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73 e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67 py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74 amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61 he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68 racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20 e hash might be
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61 void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 on returns 0 or
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 compile time.
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 ed from the .**
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 (). .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 ined at compile
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e n string. ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 pointer. ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 tion at compile
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 time..**.** See
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69 pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6c 73 65 0a 23 20 64 nt N);.#else.# d
1e00: 65 66 69 6e 65 20 73 71 6c 69 74 65 33 5f 63 6f efine sqlite3_co
1e10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 mpileoption_used
1e20: 28 58 29 20 30 0a 23 20 64 65 66 69 6e 65 20 73 (X) 0.# define s
1e30: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
1e40: 74 69 6f 6e 5f 67 65 74 28 58 29 20 20 28 28 76 tion_get(X) ((v
1e50: 6f 69 64 2a 29 30 29 0a 23 65 6e 64 69 66 0a 0a oid*)0).#endif..
1e60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1e70: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 Test To See If T
1e80: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 he Library Is Th
1e90: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e readsafe.**.** ^
1ea0: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 The sqlite3_thre
1eb0: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f adsafe() functio
1ec0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 n returns zero i
1ed0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a f and only if.**
1ee0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 SQLite was comp
1ef0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 iled with mutexi
1f00: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 ng code omitted
1f10: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 due to the.** [S
1f20: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1f30: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
1f40: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 ption being set
1f50: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 to 0..**.** SQLi
1f60: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c te can be compil
1f70: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f ed with or witho
1f80: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 ut mutexes. Whe
1f90: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 n.** the [SQLITE
1fa0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 _THREADSAFE] C p
1fb0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
1fc0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 o is 1 or 2, mut
1fd0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 exes.** are enab
1fe0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 led and SQLite i
1ff0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 s threadsafe. W
2000: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 hen the.** [SQLI
2010: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d TE_THREADSAFE] m
2020: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 acro is 0, .** t
2030: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f he mutexes are o
2040: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 mitted. Without
2050: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 the mutexes, it
2060: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 is not safe.**
2070: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f to use SQLite co
2080: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 ncurrently from
2090: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 more than one th
20a0: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 read..**.** Enab
20b0: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 ling mutexes inc
20c0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 urs a measurable
20d0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e performance pen
20e0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 alty..** So if s
20f0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 peed is of utmos
2100: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 t importance, it
2110: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 makes sense to
2120: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d disable.** the m
2130: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 utexes. But for
2140: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c maximum safety,
2150: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 mutexes should
2160: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e be enabled..** ^
2170: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 The default beha
2180: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 vior is for mute
2190: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 xes to be enable
21a0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e d..**.** This in
21b0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
21c0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 sed by an applic
21d0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 ation to make su
21e0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 re that the.** v
21f0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 ersion of SQLite
2200: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b that it is link
2210: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 ing against was
2220: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
2230: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 the desired set
2240: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c ting of the [SQL
2250: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
2260: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 macro..**.** Thi
2270: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 s interface only
2280: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 reports on the
2290: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 compile-time mut
22a0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 ex setting.** of
22b0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
22c0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 EADSAFE] flag.
22d0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
22e0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 piled with.** SQ
22f0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
2300: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 1 or =2 then mut
2310: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 exes are enabled
2320: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a by default but.
2330: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 ** can be fully
2340: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 or partially dis
2350: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 abled using a ca
2360: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
2370: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 onfig()].** with
2380: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 the verbs [SQLI
2390: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
23a0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 THREAD], [SQLITE
23b0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
23c0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c EAD],.** or [SQL
23d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
23e0: 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 LIZED]. ^(The r
23f0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
2400: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 he.** sqlite3_th
2410: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 readsafe() funct
2420: 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 ion shows only t
2430: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 he compile-time
2440: 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 setting of.** th
2450: 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 read safety, not
2460: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 any run-time ch
2470: 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 anges to that se
2480: 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a tting made by.**
2490: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
24a0: 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 ). In other word
24b0: 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 s, the return va
24c0: 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
24d0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a _threadsafe().**
24e0: 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 is unchanged by
24f0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
2500: 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 3_config().)^.**
2510: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 .** See the [thr
2520: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 eading mode] doc
2530: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 umentation for a
2540: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
2550: 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ation..*/.int sq
2560: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
2570: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 (void);../*.** C
2580: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 API3REF: Databas
2590: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e e Connection Han
25a0: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a dle.** KEYWORDS:
25b0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 {database conne
25c0: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 ction} {database
25d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a connections}.**
25e0: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 .** Each open SQ
25f0: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 Lite database is
2600: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
2610: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
2620: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 instance of.** t
2630: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 he opaque struct
2640: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 ure named "sqlit
2650: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 e3". It is usef
2660: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 ul to think of a
2670: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 n sqlite3.** poi
2680: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 nter as an objec
2690: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 t. The [sqlite3
26a0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
26b0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e e3_open16()], an
26c0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 d.** [sqlite3_op
26d0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
26e0: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 ces are its cons
26f0: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 tructors, and [s
2700: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a qlite3_close()].
2710: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
2720: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 close_v2()] are
2730: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e its destructors.
2740: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 There are many
2750: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 other.** interf
2760: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a aces (such as.**
2770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 e_v2()], [sqlite
2790: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
27a0: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 n()], and.** [sq
27b0: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
27c0: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 ut()] to name bu
27d0: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 t three) that ar
27e0: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a e methods on an.
27f0: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 ** sqlite3 objec
2800: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 t..*/.typedef st
2810: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c ruct sqlite3 sql
2820: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ite3;../*.** CAP
2830: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e I3REF: 64-Bit In
2840: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b teger Types.** K
2850: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f EYWORDS: sqlite_
2860: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e int64 sqlite_uin
2870: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 t64.**.** Becaus
2880: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 e there is no cr
2890: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 oss-platform way
28a0: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 to specify 64-b
28b0: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 it integer types
28c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 .** SQLite inclu
28d0: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 des typedefs for
28e0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 64-bit signed a
28f0: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 nd unsigned inte
2900: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 gers..**.** The
2910: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e sqlite3_int64 an
2920: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 d sqlite3_uint64
2930: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 are the preferr
2940: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 ed type definiti
2950: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ons..** The sqli
2960: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c te_int64 and sql
2970: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 ite_uint64 types
2980: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 are supported f
2990: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 or backwards.**
29a0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e compatibility on
29b0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ly..**.** ^The s
29c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 qlite3_int64 and
29d0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 sqlite_int64 ty
29e0: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e pes can store in
29f0: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 teger values.**
2a00: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 between -9223372
2a10: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 036854775808 and
2a20: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 +92233720368547
2a30: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 75807 inclusive.
2a40: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 ^The.** sqlite
2a50: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 3_uint64 and sql
2a60: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 ite_uint64 types
2a70: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 can store integ
2a80: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 er values .** be
2a90: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 tween 0 and +184
2aa0: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 4674407370955161
2ab0: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 5 inclusive..*/.
2ac0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e #ifdef SQLITE_IN
2ad0: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 T64_TYPE. typed
2ae0: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f ef SQLITE_INT64_
2af0: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 TYPE sqlite_int6
2b00: 34 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 4;.# ifdef SQLIT
2b10: 45 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 E_UINT64_TYPE.
2b20: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 typedef SQLITE
2b30: 5f 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c _UINT64_TYPE sql
2b40: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c ite_uint64;.# el
2b50: 73 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 se . typedef
2b60: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 unsigned SQLITE
2b70: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 _INT64_TYPE sqli
2b80: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 te_uint64;.# end
2b90: 69 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 if.#elif defined
2ba0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 (_MSC_VER) || de
2bb0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 fined(__BORLANDC
2bc0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f __). typedef __
2bd0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 int64 sqlite_int
2be0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 64;. typedef un
2bf0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 signed __int64 s
2c00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 qlite_uint64;.#e
2c10: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f lse. typedef lo
2c20: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 ng long int sqli
2c30: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 te_int64;. type
2c40: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e def unsigned lon
2c50: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 g long int sqlit
2c60: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 e_uint64;.#endif
2c70: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f .typedef sqlite_
2c80: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e int64 sqlite3_in
2c90: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c t64;.typedef sql
2ca0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 ite_uint64 sqlit
2cb0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a e3_uint64;../*.*
2cc0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 * If compiling f
2cd0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 or a processor t
2ce0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 hat lacks floati
2cf0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 ng point support
2d00: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 ,.** substitute
2d10: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 integer for floa
2d20: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 ting-point..*/.#
2d30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 ifdef SQLITE_OMI
2d40: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 T_FLOATING_POINT
2d50: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 .# define double
2d60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 sqlite3_int64.#
2d70: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 endif../*.** CAP
2d80: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 I3REF: Closing A
2d90: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
2da0: 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 tion.** DESTRUCT
2db0: 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OR: sqlite3.**.*
2dc0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
2dd0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 lose() and sqlit
2de0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f e3_close_v2() ro
2df0: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 utines are destr
2e00: 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 uctors.** for th
2e10: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 e [sqlite3] obje
2e20: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f ct..** ^Calls to
2e30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 sqlite3_close()
2e40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f and sqlite3_clo
2e50: 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b se_v2() return [
2e60: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a SQLITE_OK] if.**
2e70: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
2e80: 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 bject is success
2e90: 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 fully destroyed
2ea0: 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 and all associat
2eb0: 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 ed.** resources
2ec0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e are deallocated.
2ed0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 .**.** ^If the d
2ee0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2ef0: 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 on is associated
2f00: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 with unfinalize
2f10: 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 d prepared.** st
2f20: 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 atements or unfi
2f30: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 nished sqlite3_b
2f40: 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 ackup objects th
2f50: 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 en sqlite3_close
2f60: 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 ().** will leave
2f70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
2f80: 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e nnection open an
2f90: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 d return [SQLITE
2fa0: 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 _BUSY]..** ^If s
2fb0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 qlite3_close_v2(
2fc0: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 ) is called with
2fd0: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 unfinalized pre
2fe0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
2ff0: 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e .** and/or unfin
3000: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 ished sqlite3_ba
3010: 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 ckups, then the
3020: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3030: 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 ion becomes.** a
3040: 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 n unusable "zomb
3050: 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 ie" which will a
3060: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 utomatically be
3070: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e deallocated when
3080: 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 the.** last pre
3090: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
30a0: 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 is finalized or
30b0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 the last sqlite3
30c0: 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 _backup is.** fi
30d0: 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c nished. The sql
30e0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 ite3_close_v2()
30f0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 interface is int
3100: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 ended for use wi
3110: 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 th.** host langu
3120: 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 ages that are ga
3130: 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c rbage collected,
3140: 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f and where the o
3150: 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a rder in which.**
3160: 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 destructors are
3170: 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 called is arbit
3180: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c rary..**.** Appl
3190: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ications should
31a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
31b0: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c e | finalize] al
31c0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 l [prepared stat
31d0: 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c ements],.** [sql
31e0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 ite3_blob_close
31f0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c | close] all [BL
3200: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 OB handles], and
3210: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 .** [sqlite3_ba
3220: 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 ckup_finish | fi
3230: 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 nish] all [sqlit
3240: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 e3_backup] objec
3250: 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a ts associated.**
3260: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 with the [sqlit
3270: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 e3] object prior
3280: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 to attempting t
3290: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 o close the obje
32a0: 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 ct. ^If.** sqli
32b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 te3_close_v2() i
32c0: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 s called on a [d
32d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
32e0: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 on] that still h
32f0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e as.** outstandin
3300: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 g [prepared stat
3310: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 ements], [BLOB h
3320: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a andles], and/or.
3330: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b ** [sqlite3_back
3340: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e up] objects then
3350: 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c it returns [SQL
3360: 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 ITE_OK] and the
3370: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 deallocation.**
3380: 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 of resources is
3390: 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 deferred until a
33a0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ll [prepared sta
33b0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 tements], [BLOB
33c0: 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 handles],.** and
33d0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 [sqlite3_backup
33e0: 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c ] objects are al
33f0: 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a so destroyed..**
3400: 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 .** ^If an [sqli
3410: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 te3] object is d
3420: 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 estroyed while a
3430: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
3440: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 open,.** the tra
3450: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f nsaction is auto
3460: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 matically rolled
3470: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 back..**.** The
3480: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 C parameter to
3490: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 [sqlite3_close(C
34a0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
34b0: 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 close_v2(C)].**
34c0: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 must be either a
34d0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 NULL.** pointer
34e0: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d or an [sqlite3]
34f0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 object pointer
3500: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d obtained.** from
3510: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
3520: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
3530: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 16()], or.** [sq
3540: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
3550: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f , and not previo
3560: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 usly closed..**
3570: 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 ^Calling sqlite3
3580: 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 _close() or sqli
3590: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 te3_close_v2() w
35a0: 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
35b0: 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 er.** argument i
35c0: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d s a harmless no-
35d0: 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 op..*/.int sqlit
35e0: 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 e3_close(sqlite3
35f0: 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
3600: 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 close_v2(sqlite3
3610: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 *);../*.** The t
3620: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 ype for a callba
3630: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 ck function..**
3640: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 This is legacy a
3650: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 nd deprecated.
3660: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 It is included f
3670: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a or historical.**
3680: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 compatibility a
3690: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 nd is not docume
36a0: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 nted..*/.typedef
36b0: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 int (*sqlite3_c
36c0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 allback)(void*,i
36d0: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a nt,char**, char*
36e0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
36f0: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 REF: One-Step Qu
3700: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e ery Execution In
3710: 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f terface.** METHO
3720: 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
3730: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 The sqlite3_exe
3740: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 c() interface is
3750: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 a convenience w
3760: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a rapper around.**
3770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
3780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 e_v2()], [sqlite
3790: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 3_step()], and [
37a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
37b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c ()],.** that all
37c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 ows an applicati
37d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 on to run multip
37e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 le statements of
37f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 SQL.** without
3800: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 having to use a
3810: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a lot of C code. .
3820: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
3830: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 e3_exec() interf
3840: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 ace runs zero or
3850: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f more UTF-8 enco
3860: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f ded,.** semicolo
3870: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 n-separate SQL s
3880: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 tatements passed
3890: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 into its 2nd ar
38a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 gument,.** in th
38b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 e context of the
38c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
38d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e ction] passed in
38e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 as its 1st.** a
38f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 rgument. ^If th
3900: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
3910: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 ion of the 3rd a
3920: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 rgument to.** sq
3930: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
3940: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 not NULL, then i
3950: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 t is invoked for
3960: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 each result row
3970: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f .** coming out o
3980: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 f the evaluated
3990: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 SQL statements.
39a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 ^The 4th argume
39b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 nt to.** sqlite3
39c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 _exec() is relay
39d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 ed through to th
39e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f e 1st argument o
39f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 f each.** callba
3a00: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 ck invocation.
3a10: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ^If the callback
3a20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 pointer to sqli
3a30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 te3_exec().** is
3a40: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 NULL, then no c
3a50: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 allback is ever
3a60: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 invoked and resu
3a70: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 lt rows are.** i
3a80: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 gnored..**.** ^I
3a90: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 f an error occur
3aa0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 s while evaluati
3ab0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 ng the SQL state
3ac0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 ments passed int
3ad0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 o.** sqlite3_exe
3ae0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 c(), then execut
3af0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 ion of the curre
3b00: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f nt statement sto
3b10: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 ps and.** subseq
3b20: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 uent statements
3b30: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 are skipped. ^I
3b40: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 f the 5th parame
3b50: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
3b60: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 xec().** is not
3b70: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 NULL then any er
3b80: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 ror message is w
3b90: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f ritten into memo
3ba0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 ry obtained.** f
3bb0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
3bc0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 loc()] and passe
3bd0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 d back through t
3be0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
3bf0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 ..** To avoid me
3c00: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 mory leaks, the
3c10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
3c20: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 ld invoke [sqlit
3c30: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e e3_free()].** on
3c40: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
3c50: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 trings returned
3c60: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 through the 5th
3c70: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 parameter of.**
3c80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 sqlite3_exec() a
3c90: 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d fter the error m
3ca0: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 essage string is
3cb0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 no longer neede
3cc0: 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 d..** ^If the 5t
3cd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
3ce0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 qlite3_exec() is
3cf0: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f not NULL and no
3d00: 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 errors.** occur
3d10: 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 , then sqlite3_e
3d20: 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 xec() sets the p
3d30: 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 ointer in its 5t
3d40: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a h parameter to.*
3d50: 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 * NULL before re
3d60: 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e turning..**.** ^
3d70: 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 If an sqlite3_ex
3d80: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 ec() callback re
3d90: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
3da0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 the sqlite3_exec
3db0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 ().** routine re
3dc0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f turns SQLITE_ABO
3dd0: 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b RT without invok
3de0: 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ing the callback
3df0: 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 again and.** wi
3e00: 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e thout running an
3e10: 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c y subsequent SQL
3e20: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a statements..**.
3e30: 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 ** ^The 2nd argu
3e40: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 ment to the sqli
3e50: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 te3_exec() callb
3e60: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ack function is
3e70: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
3e80: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
3e90: 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 result. ^The 3r
3ea0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 d argument to th
3eb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
3ec0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 .** callback is
3ed0: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e an array of poin
3ee0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 ters to strings
3ef0: 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 obtained as if f
3f00: 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f rom.** [sqlite3_
3f10: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 column_text()],
3f20: 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c one for each col
3f30: 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 umn. ^If an ele
3f40: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 ment of a.** res
3f50: 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 ult row is NULL
3f60: 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 then the corresp
3f70: 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f onding string po
3f80: 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a inter for the.**
3f90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3fa0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 callback is a NU
3fb0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 LL pointer. ^Th
3fc0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 e 4th argument t
3fd0: 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 o the.** sqlite3
3fe0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b _exec() callback
3ff0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 is an array of
4000: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 pointers to stri
4010: 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a ngs where each.*
4020: 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e * entry represen
4030: 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 ts the name of c
4040: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 orresponding res
4050: 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 ult column as ob
4060: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b tained.** from [
4070: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
4080: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 ame()]..**.** ^I
4090: 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 f the 2nd parame
40a0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
40b0: 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 xec() is a NULL
40c0: 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 pointer, a point
40d0: 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 er.** to an empt
40e0: 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 y string, or a p
40f0: 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 ointer that cont
4100: 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 ains only whites
4110: 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 pace and/or .**
4120: 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 SQL comments, th
4130: 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d en no SQL statem
4140: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 ents are evaluat
4150: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 ed and the datab
4160: 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 ase.** is not ch
4170: 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 anged..**.** Res
4180: 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a trictions:.**.**
4190: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 <ul>.** <li> Th
41a0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
41b0: 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 st ensure that t
41c0: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 he 1st parameter
41d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 to sqlite3_exec
41e0: 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 ().** is a
41f0: 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b valid and open [
4200: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
4210: 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 ion]..** <li> Th
4220: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
4230: 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 st not close the
4240: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
4250: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 ction] specified
4260: 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 by.** the
4270: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 1st parameter to
4280: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
4290: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 while sqlite3_ex
42a0: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e ec() is running.
42b0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 .** <li> The app
42c0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f lication must no
42d0: 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c t modify the SQL
42e0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 statement text
42f0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 passed into.**
4300: 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 the 2nd para
4310: 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 meter of sqlite3
4320: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 _exec() while sq
4330: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
4340: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c running..** </ul
4350: 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 >.*/.int sqlite3
4360: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 _exec(. sqlite3
4370: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *,
4380: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4390: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 /* An open d
43a0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e atabase */. con
43b0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 st char *sql,
43c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
43d0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 /* SQL t
43e0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a o be evaluated *
43f0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 /. int (*callba
4400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 ck)(void*,int,ch
4410: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f ar**,char**), /
4420: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * Callback funct
4430: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c ion */. void *,
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4450: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4460: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d /* 1st argum
4470: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 ent to callback
4480: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d */. char **errm
4490: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 sg
44a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
44b0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 /* Error msg wri
44c0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a tten here */.);.
44d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
44e0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a Result Codes.**
44f0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 KEYWORDS: {resu
4500: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 lt code definiti
4510: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 ons}.**.** Many
4520: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 SQLite functions
4530: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 return an integ
4540: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 er result code f
4550: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 rom the set show
4560: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 n.** here in ord
4570: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 er to indicate s
4580: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 uccess or failur
4590: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 e..**.** New err
45a0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 or codes may be
45b0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
45c0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
45d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c te..**.** See al
45e0: 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 so: [extended re
45f0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 sult code defini
4600: 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e tions].*/.#defin
4610: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 e SQLITE_OK
4620: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 0 /* Suc
4630: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a cessful result *
4640: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f /./* beginning-o
4650: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f f-error-codes */
4660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4670: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 ERROR 1
4680: 20 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f /* Generic erro
4690: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
46a0: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 ITE_INTERNAL
46b0: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 2 /* Internal
46c0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 logic error in
46d0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e SQLite */.#defin
46e0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 e SQLITE_PERM
46f0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 3 /* Acc
4700: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 ess permission d
4710: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 enied */.#define
4720: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 SQLITE_ABORT
4730: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 4 /* Call
4740: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 back routine req
4750: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 uested an abort
4760: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4770: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 E_BUSY 5
4780: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 /* The databa
4790: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 se file is locke
47a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
47b0: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 ITE_LOCKED
47c0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 6 /* A table
47d0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 in the database
47e0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 is locked */.#de
47f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 fine SQLITE_NOME
4800: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 M 7 /*
4810: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 A malloc() faile
4820: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4830: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 ITE_READONLY
4840: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 8 /* Attempt
4850: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f to write a reado
4860: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a nly database */.
4870: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4880: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 NTERRUPT 9
4890: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 /* Operation ter
48a0: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 minated by sqlit
48b0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f e3_interrupt()*/
48c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
48d0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 IOERR 10
48e0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 /* Some kind of
48f0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 disk I/O error
4900: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 occurred */.#def
4910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 ine SQLITE_CORRU
4920: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 PT 11 /* T
4930: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b he database disk
4940: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 image is malfor
4950: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 med */.#define S
4960: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 QLITE_NOTFOUND
4970: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 12 /* Unknow
4980: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 n opcode in sqli
4990: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
49a0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
49b0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 LITE_FULL
49c0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 13 /* Inserti
49d0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 on failed becaus
49e0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 e database is fu
49f0: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ll */.#define SQ
4a00: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 LITE_CANTOPEN
4a10: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 14 /* Unable
4a20: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 to open the data
4a30: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 base file */.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 fine SQLITE_PROT
4a50: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 OCOL 15 /*
4a60: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 Database lock pr
4a70: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a otocol error */.
4a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 #define SQLITE_E
4a90: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 MPTY 16
4aa0: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 /* Internal use
4ab0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
4ac0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 SQLITE_SCHEMA
4ad0: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 17 /* The d
4ae0: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 atabase schema c
4af0: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e hanged */.#defin
4b00: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 e SQLITE_TOOBIG
4b10: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 18 /* Str
4b20: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 ing or BLOB exce
4b30: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a eds size limit *
4b40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4b50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 _CONSTRAINT 19
4b60: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 /* Abort due t
4b70: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f o constraint vio
4b80: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e lation */.#defin
4b90: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 e SQLITE_MISMATC
4ba0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 H 20 /* Dat
4bb0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 a type mismatch
4bc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4bd0: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 E_MISUSE 21
4be0: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 /* Library us
4bf0: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a ed incorrectly *
4c00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4c10: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 _NOLFS 22
4c20: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 /* Uses OS fea
4c30: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 tures not suppor
4c40: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 ted on host */.#
4c50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 define SQLITE_AU
4c60: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f TH 23 /
4c70: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 * Authorization
4c80: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e denied */.#defin
4c90: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 e SQLITE_FORMAT
4ca0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 24 /* Not
4cb0: 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 used */.#define
4cc0: 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 SQLITE_RANGE
4cd0: 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 25 /* 2nd
4ce0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
4cf0: 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 ite3_bind out of
4d00: 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e range */.#defin
4d10: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 e SQLITE_NOTADB
4d20: 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 26 /* Fil
4d30: 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 e opened that is
4d40: 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 not a database
4d50: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 file */.#define
4d60: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 SQLITE_NOTICE
4d70: 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 27 /* Notif
4d80: 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 ications from sq
4d90: 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 lite3_log() */.#
4da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 define SQLITE_WA
4db0: 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f RNING 28 /
4dc0: 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 * Warnings from
4dd0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f sqlite3_log() */
4de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4df0: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 ROW 100
4e00: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 /* sqlite3_step
4e10: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 () has another r
4e20: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 ow ready */.#def
4e30: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 ine SQLITE_DONE
4e40: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 101 /* s
4e50: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 qlite3_step() ha
4e60: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 s finished execu
4e70: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f ting */./* end-o
4e80: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f f-error-codes */
4e90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
4ea0: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c : Extended Resul
4eb0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f t Codes.** KEYWO
4ec0: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 RDS: {extended r
4ed0: 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e esult code defin
4ee0: 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e itions}.**.** In
4ef0: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e its default con
4f00: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 figuration, SQLi
4f10: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 te API routines
4f20: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 return one of 30
4f30: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 integer.** [res
4f40: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 ult codes]. How
4f50: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 ever, experience
4f60: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 has shown that
4f70: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 many of.** these
4f80: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 result codes ar
4f90: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 e too coarse-gra
4fa0: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e ined. They do n
4fb0: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a ot provide as.**
4fc0: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f much informatio
4fd0: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 n about problems
4fe0: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 as programmers
4ff0: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 might like. In
5000: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 an effort to.**
5010: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 address this, ne
5020: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 wer versions of
5030: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 SQLite (version
5040: 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 3.3.8 [dateof:3.
5050: 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 3.8].** and late
5060: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 r) include.** su
5070: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 pport for additi
5080: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 onal result code
5090: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d s that provide m
50a0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 ore detailed inf
50b0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 ormation.** abou
50c0: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 t errors. These
50d0: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
50e0: 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 codes] are enab
50f0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a led or disabled.
5100: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 ** on a per data
5110: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
5120: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a basis using the.
5130: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 ** [sqlite3_exte
5140: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
5150: 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 s()] API. Or, t
5160: 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 he extended code
5170: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 for.** the most
5180: 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 recent error ca
5190: 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 n be obtained us
51a0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
51b0: 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 extended_errcode
51c0: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ()]..*/.#define
51d0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 SQLITE_ERROR_MIS
51e0: 53 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 SING_COLLSEQ (
51f0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 SQLITE_ERROR | (
5200: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
5210: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 QLITE_ERROR_RETR
5220: 59 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 Y (S
5230: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 QLITE_ERROR | (2
5240: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5250: 4c 49 54 45 5f 45 52 52 4f 52 5f 53 4e 41 50 53 LITE_ERROR_SNAPS
5260: 48 4f 54 20 20 20 20 20 20 20 20 20 20 28 53 51 HOT (SQ
5270: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 33 3c LITE_ERROR | (3<
5280: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5290: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 ITE_IOERR_READ
52a0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
52b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c ITE_IOERR | (1<<
52c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
52d0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
52e0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 EAD (SQLI
52f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 TE_IOERR | (2<<8
5300: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5310: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 E_IOERR_WRITE
5320: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5330: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 E_IOERR | (3<<8)
5340: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5350: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 _IOERR_FSYNC
5360: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5370: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 _IOERR | (4<<8))
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5390: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 IOERR_DIR_FSYNC
53a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
53b0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a IOERR | (5<<8)).
53c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
53d0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 OERR_TRUNCATE
53e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
53f0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 OERR | (6<<8)).#
5400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5410: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 ERR_FSTAT
5420: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5430: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 ERR | (7<<8)).#d
5440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5450: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 RR_UNLOCK
5460: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5470: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 RR | (8<<8)).#de
5480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
5490: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 R_RDLOCK
54a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
54b0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 R | (9<<8)).#def
54c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
54d0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
54e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
54f0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 | (10<<8)).#def
5500: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5510: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 _BLOCKED
5520: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5530: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 | (11<<8)).#def
5540: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5550: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 _NOMEM
5560: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5570: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 | (12<<8)).#def
5580: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5590: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 _ACCESS
55a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
55b0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 | (13<<8)).#def
55c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
55d0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f _CHECKRESERVEDLO
55e0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 CK (SQLITE_IOERR
55f0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 | (14<<8)).#def
5600: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5610: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 _LOCK
5620: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5630: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 | (15<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5650: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 _CLOSE
5660: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5670: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 | (16<<8)).#def
5680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5690: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 _DIR_CLOSE
56a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
56b0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 | (17<<8)).#def
56c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
56d0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 _SHMOPEN
56e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
56f0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 | (18<<8)).#def
5700: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5710: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 _SHMSIZE
5720: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5730: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 | (19<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5750: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 _SHMLOCK
5760: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5770: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 | (20<<8)).#def
5780: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5790: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 _SHMMAP
57a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
57b0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 | (21<<8)).#def
57c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
57d0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 _SEEK
57e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
57f0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 | (22<<8)).#def
5800: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5810: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 _DELETE_NOENT
5820: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5830: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 | (23<<8)).#def
5840: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5850: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 _MMAP
5860: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5870: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 | (24<<8)).#def
5880: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5890: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 _GETTEMPPATH
58a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
58b0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 | (25<<8)).#def
58c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
58d0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 _CONVPATH
58e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
58f0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 | (26<<8)).#def
5900: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5910: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20 _VNODE
5920: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5930: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 | (27<<8)).#def
5940: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5950: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20 _AUTH
5960: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5970: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66 | (28<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5990: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20 _BEGIN_ATOMIC
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
59b0: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66 | (29<<8)).#def
59c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
59d0: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20 _COMMIT_ATOMIC
59e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
59f0: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66 | (30<<8)).#def
5a00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5a10: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 _ROLLBACK_ATOMIC
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5a30: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66 | (31<<8)).#def
5a40: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 ine SQLITE_LOCKE
5a50: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 D_SHAREDCACHE
5a60: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 (SQLITE_LOCKE
5a70: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 D | (1<<8)).#de
5a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
5a90: 45 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 ED_VTAB
5aa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b (SQLITE_LOCK
5ab0: 45 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 ED | (2<<8)).#d
5ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
5ad0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 Y_RECOVERY
5ae0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 (SQLITE_BUS
5af0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 Y | (1<<8)).#
5b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 define SQLITE_BU
5b10: 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 SY_SNAPSHOT
5b20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 (SQLITE_BU
5b30: 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a SY | (2<<8)).
5b40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5b50: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 ANTOPEN_NOTEMPDI
5b60: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 R (SQLITE_C
5b70: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 ANTOPEN | (1<<8)
5b80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5b90: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 _CANTOPEN_ISDIR
5ba0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5bb0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c _CANTOPEN | (2<<
5bc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5bd0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c TE_CANTOPEN_FULL
5be0: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 PATH (SQLI
5bf0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 TE_CANTOPEN | (3
5c00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5c10: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f LITE_CANTOPEN_CO
5c20: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 NVPATH (SQ
5c30: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 LITE_CANTOPEN |
5c40: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (4<<8)).#define
5c50: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f SQLITE_CANTOPEN_
5c60: 44 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28 DIRTYWAL (
5c70: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 SQLITE_CANTOPEN
5c80: 7c 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74 | (5<<8)) /* Not
5c90: 20 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 Used */.#define
5ca0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f SQLITE_CORRUPT_
5cb0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 VTAB
5cc0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 (SQLITE_CORRUPT
5cd0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
5ce0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 e SQLITE_CORRUPT
5cf0: 5f 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20 _SEQUENCE
5d00: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 (SQLITE_CORRUPT
5d10: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
5d20: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e ne SQLITE_READON
5d30: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 LY_RECOVERY
5d40: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e (SQLITE_READON
5d50: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 LY | (1<<8)).#de
5d60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
5d70: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 ONLY_CANTLOCK
5d80: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 (SQLITE_READ
5d90: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 ONLY | (2<<8)).#
5da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
5db0: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 ADONLY_ROLLBACK
5dc0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 (SQLITE_RE
5dd0: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 ADONLY | (3<<8))
5de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5df0: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 READONLY_DBMOVED
5e00: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5e10: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 READONLY | (4<<8
5e20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5e30: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 E_READONLY_CANTI
5e40: 4e 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54 NIT (SQLIT
5e50: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c E_READONLY | (5<
5e60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5e70: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 ITE_READONLY_DIR
5e80: 45 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c ECTORY (SQL
5e90: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 ITE_READONLY | (
5ea0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 6<<8)).#define S
5eb0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c QLITE_ABORT_ROLL
5ec0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 BACK (S
5ed0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 QLITE_ABORT | (2
5ee0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5ef0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
5f00: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 CHECK (SQ
5f10: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
5f20: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
5f30: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
5f40: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 INT_COMMITHOOK
5f50: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 (SQLITE_CONSTRA
5f60: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 INT | (2<<8)).#d
5f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
5f80: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b STRAINT_FOREIGNK
5f90: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e EY (SQLITE_CON
5fa0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 STRAINT | (3<<8)
5fb0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5fc0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 _CONSTRAINT_FUNC
5fd0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 TION (SQLITE
5fe0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 _CONSTRAINT | (4
5ff0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6000: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
6010: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 NOTNULL (SQ
6020: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
6030: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (5<<8)).#defin
6040: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
6050: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 INT_PRIMARYKEY
6060: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 (SQLITE_CONSTRA
6070: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 INT | (6<<8)).#d
6080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
6090: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 STRAINT_TRIGGER
60a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e (SQLITE_CON
60b0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 STRAINT | (7<<8)
60c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
60d0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 _CONSTRAINT_UNIQ
60e0: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 UE (SQLITE
60f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 _CONSTRAINT | (8
6100: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6110: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
6120: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 VTAB (SQ
6130: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
6140: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (9<<8)).#defin
6150: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
6160: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 INT_ROWID
6170: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 (SQLITE_CONSTRA
6180: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 INT |(10<<8)).#d
6190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 efine SQLITE_NOT
61a0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 ICE_RECOVER_WAL
61b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 (SQLITE_NOT
61c0: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 ICE | (1<<8)).#d
61d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 efine SQLITE_NOT
61e0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c ICE_RECOVER_ROLL
61f0: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 BACK (SQLITE_NOT
6200: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 ICE | (2<<8)).#d
6210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 efine SQLITE_WAR
6220: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 NING_AUTOINDEX
6230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 (SQLITE_WAR
6240: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 NING | (1<<8)).#
6250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 define SQLITE_AU
6260: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 TH_USER
6270: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 (SQLITE_AU
6280: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 TH | (1<<8)).#de
6290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c fine SQLITE_OK_L
62a0: 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 OAD_PERMANENTLY
62b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c (SQLITE_OK |
62c0: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 (1<<8))../*.**
62d0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 CAPI3REF: Flags
62e0: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 For File Open Op
62f0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 erations.**.** T
6300: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 hese bit values
6310: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 are intended for
6320: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 use in the.** 3
6330: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
6340: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 the [sqlite3_ope
6350: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 n_v2()] interfac
6360: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 e and.** in the
6370: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
6380: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
6390: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e s.xOpen] method.
63a0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
63b0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
63c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
63d0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 001 /* Ok for s
63e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
63f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6400: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
6410: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 E 0x00000
6420: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 002 /* Ok for s
6430: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
6440: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6450: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 TE_OPEN_CREATE
6460: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6470: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 004 /* Ok for s
6480: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
6490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
64a0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
64b0: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 CLOSE 0x00000
64c0: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 008 /* VFS only
64d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
64e0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 TE_OPEN_EXCLUSIV
64f0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 E 0x00000
6500: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 010 /* VFS only
6510: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6520: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 TE_OPEN_AUTOPROX
6530: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 Y 0x00000
6540: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 020 /* VFS only
6550: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6560: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 TE_OPEN_URI
6570: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6580: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 040 /* Ok for s
6590: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
65a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
65b0: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 TE_OPEN_MEMORY
65c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
65d0: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 080 /* Ok for s
65e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
65f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6600: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 TE_OPEN_MAIN_DB
6610: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6620: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 100 /* VFS only
6630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6640: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 TE_OPEN_TEMP_DB
6650: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6660: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 200 /* VFS only
6670: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6680: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e TE_OPEN_TRANSIEN
6690: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 T_DB 0x00000
66a0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 400 /* VFS only
66b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
66c0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 TE_OPEN_MAIN_JOU
66d0: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 RNAL 0x00000
66e0: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 800 /* VFS only
66f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6700: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 TE_OPEN_TEMP_JOU
6710: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 RNAL 0x00001
6720: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
6730: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6740: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e TE_OPEN_SUBJOURN
6750: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 AL 0x00002
6760: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
6770: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6780: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a TE_OPEN_MASTER_J
6790: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 OURNAL 0x00004
67a0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
67b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
67c0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 TE_OPEN_NOMUTEX
67d0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 0x00008
67e0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
67f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
6800: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6810: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 TE_OPEN_FULLMUTE
6820: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 X 0x00010
6830: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
6840: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
6850: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6860: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
6870: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 CHE 0x00020
6880: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
6890: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
68a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
68b0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
68c0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 ACHE 0x00040
68d0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
68e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
68f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6900: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 TE_OPEN_WAL
6910: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 0x00080
6920: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
6930: 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 */../* Reserved
6940: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 :
6950: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 0x00F0
6960: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 0000 */../*.** C
6970: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 API3REF: Device
6980: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a Characteristics.
6990: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 **.** The xDevic
69a0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 eCharacteristics
69b0: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b method of the [
69c0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
69d0: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 ds].** object re
69e0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 turns an integer
69f0: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 which is a vect
6a00: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 or of these.** b
6a10: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 it values expres
6a20: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 sing I/O charact
6a30: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 eristics of the
6a40: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 mass storage.**
6a50: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 device that hold
6a60: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 s the file that
6a70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
6a80: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 methods].** refe
6a90: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 rs to..**.** The
6aa0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6ab0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 OMIC property me
6ac0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 ans that all wri
6ad0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 tes of.** any si
6ae0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 ze are atomic.
6af0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
6b00: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 _ATOMICnnn value
6b10: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 s.** mean that w
6b20: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 rites of blocks
6b30: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 that are nnn byt
6b40: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a es in size and.*
6b50: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f * are aligned to
6b60: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 an address whic
6b70: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 h is an integer
6b80: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e multiple of.** n
6b90: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 nn are atomic.
6ba0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
6bb0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c _SAFE_APPEND val
6bc0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 ue means.** that
6bd0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 when data is ap
6be0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 pended to a file
6bf0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 , the data is ap
6c00: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 pended.** first
6c10: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 then the size of
6c20: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 the file is ext
6c30: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 ended, never the
6c40: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 other.** way ar
6c50: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 ound. The SQLIT
6c60: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
6c70: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e AL property mean
6c80: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d s that.** inform
6c90: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e ation is written
6ca0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 to disk in the
6cb0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 same order as ca
6cc0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 lls.** to xWrite
6cd0: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f (). The SQLITE_
6ce0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f IOCAP_POWERSAFE_
6cf0: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 OVERWRITE proper
6d00: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a ty means that.**
6d10: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f after reboot fo
6d20: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 llowing a crash
6d30: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 or power loss, t
6d40: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e he only bytes in
6d50: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 a.** file that
6d60: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 were written at
6d70: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
6d80: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 level might have
6d90: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 changed.** and
6da0: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 that adjacent by
6db0: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 tes, even bytes
6dc0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 within the same
6dd0: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 sector are.** gu
6de0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 aranteed to be u
6df0: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 nchanged. The S
6e00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 QLITE_IOCAP_UNDE
6e10: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 LETABLE_WHEN_OPE
6e20: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 N.** flag indica
6e30: 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 tes that a file
6e40: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 cannot be delete
6e50: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 d when open. Th
6e60: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 e.** SQLITE_IOCA
6e70: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 P_IMMUTABLE flag
6e80: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 indicates that
6e90: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a the file is on.*
6ea0: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 * read-only medi
6eb0: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 a and cannot be
6ec0: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 changed even by
6ed0: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a processes with.*
6ee0: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 * elevated privi
6ef0: 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 leges..**.** The
6f00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 SQLITE_IOCAP_BA
6f10: 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 TCH_ATOMIC prope
6f20: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74 rty means that t
6f30: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a he underlying.**
6f40: 20 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70 filesystem supp
6f50: 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 orts doing multi
6f60: 70 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74 ple write operat
6f70: 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 ions atomically
6f80: 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 when those.** wr
6f90: 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 ite operations a
6fa0: 72 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20 re bracketed by
6fb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 [SQLITE_FCNTL_BE
6fc0: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 GIN_ATOMIC_WRITE
6fd0: 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 ] and.** [SQLITE
6fe0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 _FCNTL_COMMIT_AT
6ff0: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a OMIC_WRITE]..*/.
7000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7010: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 OCAP_ATOMIC
7020: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
7030: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 000001.#define S
7040: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7050: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 IC512
7060: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 0x00000002.#d
7070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
7080: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 AP_ATOMIC1K
7090: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
70a0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 0004.#define SQL
70b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
70c0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2K
70d0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 0x00000008.#def
70e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
70f0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 _ATOMIC4K
7100: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
7110: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 10.#define SQLIT
7120: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b E_IOCAP_ATOMIC8K
7130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
7140: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e x00000020.#defin
7150: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
7160: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 TOMIC16K
7170: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0x00000040
7180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7190: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 IOCAP_ATOMIC32K
71a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
71b0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 0000080.#define
71c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
71d0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 MIC64K
71e0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 0x00000100.#
71f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
7200: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
7210: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
7220: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 00200.#define SQ
7230: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
7240: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 NTIAL
7250: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 0x00000400.#de
7260: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
7270: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 P_UNDELETABLE_WH
7280: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 EN_OPEN 0x00000
7290: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 800.#define SQLI
72a0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 TE_IOCAP_POWERSA
72b0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 FE_OVERWRITE
72c0: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 0x00001000.#defi
72d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
72e0: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 IMMUTABLE
72f0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 0x0000200
7300: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
7310: 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f _IOCAP_BATCH_ATO
7320: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78 MIC 0x
7330: 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 00004000../*.**
7340: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c CAPI3REF: File L
7350: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a ocking Levels.**
7360: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 .** SQLite uses
7370: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 one of these int
7380: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 eger values as t
7390: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 he second.** arg
73a0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 ument to calls i
73b0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 t makes to the x
73c0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f Lock() and xUnlo
73d0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 ck() methods.**
73e0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 of an [sqlite3_i
73f0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
7400: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t..*/.#define SQ
7410: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 LITE_LOCK_NONE
7420: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 0.#defin
7430: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 e SQLITE_LOCK_SH
7440: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 ARED 1.#d
7450: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
7460: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 K_RESERVED
7470: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
7480: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 _LOCK_PENDING
7490: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
74a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 LITE_LOCK_EXCLUS
74b0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a IVE 4../*.**
74c0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 CAPI3REF: Synch
74d0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 ronization Type
74e0: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e Flags.**.** When
74f0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 SQLite invokes
7500: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 the xSync() meth
7510: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c od of an.** [sql
7520: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
7530: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 object it uses
7540: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 a combination of
7550: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 .** these intege
7560: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 r values as the
7570: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e second argument.
7580: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
7590: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 SQLITE_SYNC_DATA
75a0: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 ONLY flag is use
75b0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 d, it means that
75c0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 the.** sync ope
75d0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 ration only need
75e0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 s to flush data
75f0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e to mass storage.
7600: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 Inode.** infor
7610: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 mation need not
7620: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 be flushed. If t
7630: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 he lower four bi
7640: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a ts of the flag.*
7650: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 * equal SQLITE_S
7660: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 YNC_NORMAL, that
7670: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f means to use no
7680: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d rmal fsync() sem
7690: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 antics..** If th
76a0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 e lower four bit
76b0: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 s equal SQLITE_S
76c0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d YNC_FULL, that m
76d0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d eans.** to use M
76e0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 ac OS X style fu
76f0: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f llsync instead o
7700: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a f fsync()..**.**
7710: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 Do not confuse
7720: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f the SQLITE_SYNC_
7730: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 NORMAL and SQLIT
7740: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 E_SYNC_FULL flag
7750: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 s.** with the [P
7760: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
7770: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 s]=NORMAL and [P
7780: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
7790: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 s]=FULL.** setti
77a0: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 ngs. The [synch
77b0: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 ronous pragma] d
77c0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 etermines when c
77d0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 alls to the.** x
77e0: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 Sync VFS method
77f0: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 occur and applie
7800: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f s uniformly acro
7810: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 ss all platforms
7820: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f ..** The SQLITE_
7830: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 SYNC_NORMAL and
7840: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
7850: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 flags determine
7860: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 how.** energeti
7870: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 c or rigorous or
7880: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 forceful the sy
7890: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 nc operations ar
78a0: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 e and.** only ma
78b0: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 ke a difference
78c0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 on Mac OSX for t
78d0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 he default SQLit
78e0: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 e code..** (Thir
78f0: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c d-party VFS impl
7900: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 ementations migh
7910: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 t also make the
7920: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 distinction.** b
7930: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 etween SQLITE_SY
7940: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 NC_NORMAL and SQ
7950: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 LITE_SYNC_FULL,
7960: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a but among the.**
7970: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
7980: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 ms natively supp
7990: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c orted by SQLite,
79a0: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a only Mac OSX.**
79b0: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 cares about the
79c0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f difference.).*/
79d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
79e0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 SYNC_NORMAL
79f0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 0x00002.#defi
7a00: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 ne SQLITE_SYNC_F
7a10: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 ULL 0x0
7a20: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 0003.#define SQL
7a30: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c ITE_SYNC_DATAONL
7a40: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a Y 0x00010..
7a50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
7a60: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 OS Interface Ope
7a70: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a n File Handle.**
7a80: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f .** An [sqlite3_
7a90: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 file] object rep
7aa0: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 resents an open
7ab0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 file in the .**
7ac0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f [sqlite3_vfs | O
7ad0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 S interface laye
7ae0: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 r]. Individual
7af0: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 OS interface.**
7b00: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
7b10: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 will.** want to
7b20: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 subclass this ob
7b30: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e ject by appendin
7b40: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 g additional fie
7b50: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 lds.** for their
7b60: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 own use. The p
7b70: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 Methods entry is
7b80: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
7b90: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f .** [sqlite3_io_
7ba0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
7bb0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 that defines met
7bc0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d hods for perform
7bd0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 ing.** I/O opera
7be0: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 tions on the ope
7bf0: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 n file..*/.typed
7c00: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
7c10: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 3_file sqlite3_f
7c20: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ile;.struct sqli
7c30: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e te3_file {. con
7c40: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 st struct sqlite
7c50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 3_io_methods *pM
7c60: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 ethods; /* Meth
7c70: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 ods for an open
7c80: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a file */.};../*.*
7c90: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 * CAPI3REF: OS I
7ca0: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 nterface File Vi
7cb0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 rtual Methods Ob
7cc0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 ject.**.** Every
7cd0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 file opened by
7ce0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
7cf0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 .xOpen] method p
7d00: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b opulates an.** [
7d10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
7d20: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 ject (or, more c
7d30: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c ommonly, a subcl
7d40: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 ass of the.** [s
7d50: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
7d60: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e ect) with a poin
7d70: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
7d80: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
7d90: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 t..** This objec
7da0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 t defines the me
7db0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 thods used to pe
7dc0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 rform various op
7dd0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 erations.** agai
7de0: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c nst the open fil
7df0: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 e represented by
7e00: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
7e10: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a le] object..**.*
7e20: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * If the [sqlite
7e30: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 3_vfs.xOpen] met
7e40: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c hod sets the sql
7e50: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
7e60: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 ds element .** t
7e70: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 o a non-NULL poi
7e80: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 nter, then the s
7e90: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
7ea0: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a s.xClose method.
7eb0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 ** may be invoke
7ec0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 d even if the [s
7ed0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
7ee0: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 ] reported that
7ef0: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a it failed. The.
7f00: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 ** only way to p
7f10: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f revent a call to
7f20: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e xClose followin
7f30: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 g a failed [sqli
7f40: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a te3_vfs.xOpen].*
7f50: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 * is for the [sq
7f60: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
7f70: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 to set the sqli
7f80: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
7f90: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 s element.** to
7fa0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 NULL..**.** The
7fb0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
7fc0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f o xSync may be o
7fd0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 ne of [SQLITE_SY
7fe0: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a NC_NORMAL] or.**
7ff0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 [SQLITE_SYNC_FU
8000: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 LL]. The first
8010: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f choice is the no
8020: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a rmal fsync()..**
8030: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 The second choi
8040: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 ce is a Mac OS X
8050: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e style fullsync.
8060: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 The [SQLITE_SY
8070: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 NC_DATAONLY].**
8080: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 flag may be ORed
8090: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 in to indicate
80a0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 that only the da
80b0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a ta of the file.*
80c0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e * and not its in
80d0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 ode needs to be
80e0: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 synced..**.** Th
80f0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
8100: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 to xLock() and
8110: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e xUnlock() are on
8120: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 e of.** <ul>.**
8130: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
8140: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e K_NONE],.** <li>
8150: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 [SQLITE_LOCK_SH
8160: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b ARED],.** <li> [
8170: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
8180: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b RVED],.** <li> [
8190: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 SQLITE_LOCK_PEND
81a0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e ING], or.** <li>
81b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 [SQLITE_LOCK_EX
81c0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 CLUSIVE]..** </u
81d0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e l>.** xLock() in
81e0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b creases the lock
81f0: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 . xUnlock() decr
8200: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a eases the lock..
8210: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 ** The xCheckRes
8220: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 ervedLock() meth
8230: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 od checks whethe
8240: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 r any database c
8250: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 onnection,.** ei
8260: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f ther in this pro
8270: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 cess or in some
8280: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 other process, i
8290: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 s holding a RESE
82a0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 RVED,.** PENDING
82b0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c , or EXCLUSIVE l
82c0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e ock on the file.
82d0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 It returns tru
82e0: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c e.** if such a l
82f0: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 ock exists and f
8300: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a alse otherwise..
8310: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 **.** The xFileC
8320: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 ontrol() method
8330: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 is a generic int
8340: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f erface that allo
8350: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 ws custom.** VFS
8360: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
8370: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e to directly con
8380: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c trol an open fil
8390: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b e using the.** [
83a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
83b0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 trol()] interfac
83c0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 e. The second "
83d0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 op" argument is
83e0: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 an.** integer op
83f0: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 code. The third
8400: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 argument is a g
8410: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 eneric pointer i
8420: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f ntended to.** po
8430: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 int to a structu
8440: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 re that may cont
8450: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 ain arguments or
8460: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 space in which
8470: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 to.** write retu
8480: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 rn values. Pote
8490: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 ntial uses for x
84a0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 FileControl() mi
84b0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 ght be.** functi
84c0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c ons to enable bl
84d0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 ocking locks wit
84e0: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 h timeouts, to c
84f0: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 hange the.** loc
8500: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 king strategy (f
8510: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 or example to us
8520: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 e dot-file locks
8530: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a ), to inquire.**
8540: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 about the statu
8550: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 s of a lock, or
8560: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c to break stale l
8570: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 ocks. The SQLit
8580: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 e.** core reserv
8590: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c es all opcodes l
85a0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 ess than 100 for
85b0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a its own use..**
85c0: 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c A [file control
85d0: 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 opcodes | list
85e0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 of opcodes] less
85f0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 than 100 is ava
8600: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 ilable..** Appli
8610: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 cations that def
8620: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 ine a custom xFi
8630: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
8640: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f should use opco
8650: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 des.** greater t
8660: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 han 100 to avoid
8670: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 conflicts. VFS
8680: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
8690: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 should.** retur
86a0: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 n [SQLITE_NOTFOU
86b0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e ND] for file con
86c0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 trol opcodes tha
86d0: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a t they do not.**
86e0: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a recognize..**.*
86f0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a * The xSectorSiz
8700: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 e() method retur
8710: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 ns the sector si
8720: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 ze of the.** dev
8730: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 ice that underli
8740: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 es the file. Th
8750: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 e sector size is
8760: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 the.** minimum
8770: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 write that can b
8780: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 e performed with
8790: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a out disturbing.*
87a0: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e * other bytes in
87b0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 the file. The
87c0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 xDeviceCharacter
87d0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 istics().** meth
87e0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 od returns a bit
87f0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 vector describi
8800: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 ng behaviors of
8810: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e the.** underlyin
8820: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 g device:.**.**
8830: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
8840: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8850: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 C].** <li> [SQLI
8860: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 TE_IOCAP_ATOMIC5
8870: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 12].** <li> [SQL
8880: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
8890: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 1K].** <li> [SQL
88a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
88b0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 2K].** <li> [SQL
88c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
88d0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 4K].** <li> [SQL
88e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
88f0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 8K].** <li> [SQL
8900: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
8910: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 16K].** <li> [SQ
8920: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8930: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C32K].** <li> [S
8940: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
8950: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC64K].** <li> [
8960: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 SQLITE_IOCAP_SAF
8970: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 E_APPEND].** <li
8980: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
8990: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c SEQUENTIAL].** <
89a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
89b0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 P_UNDELETABLE_WH
89c0: 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e EN_OPEN].** <li>
89d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 [SQLITE_IOCAP_P
89e0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
89f0: 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c TE].** <li> [SQL
8a00: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 ITE_IOCAP_IMMUTA
8a10: 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 BLE].** <li> [SQ
8a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 LITE_IOCAP_BATCH
8a30: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c _ATOMIC].** </ul
8a40: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 >.**.** The SQLI
8a50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 TE_IOCAP_ATOMIC
8a60: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
8a70: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f hat all writes o
8a80: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 f.** any size ar
8a90: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
8aa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
8ab0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 ICnnn values.**
8ac0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 mean that writes
8ad0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 of blocks that
8ae0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e are nnn bytes in
8af0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 size and.** are
8b00: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 aligned to an a
8b10: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 ddress which is
8b20: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 an integer multi
8b30: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 ple of.** nnn ar
8b40: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
8b50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
8b60: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 _APPEND value me
8b70: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e ans.** that when
8b80: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
8b90: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 d to a file, the
8ba0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
8bb0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 d.** first then
8bc0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
8bd0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 file is extended
8be0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 , never the othe
8bf0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e r.** way around.
8c00: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
8c10: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 AP_SEQUENTIAL pr
8c20: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
8c30: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e t.** information
8c40: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 is written to d
8c50: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 isk in the same
8c60: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a order as calls.*
8c70: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a * to xWrite()..*
8c80: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 *.** If xRead()
8c90: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 returns SQLITE_I
8ca0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 OERR_SHORT_READ
8cb0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c it must also fil
8cc0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 l.** in the unre
8cd0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 ad portions of t
8ce0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a he buffer with z
8cf0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 eros. A VFS tha
8d00: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 t.** fails to ze
8d10: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 ro-fill short re
8d20: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 ads might seem t
8d30: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 o work. However
8d40: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 ,.** failure to
8d50: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 zero-fill short
8d60: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 reads will event
8d70: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a ually lead to.**
8d80: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 database corrup
8d90: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 tion..*/.typedef
8da0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
8db0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 io_methods sqlit
8dc0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 e3_io_methods;.s
8dd0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f truct sqlite3_io
8de0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 _methods {. int
8df0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 iVersion;. int
8e00: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 (*xClose)(sqlit
8e10: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 e3_file*);. int
8e20: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 (*xRead)(sqlite
8e30: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 3_file*, void*,
8e40: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 int iAmt, sqlite
8e50: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 3_int64 iOfst);.
8e60: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 int (*xWrite)(
8e70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 sqlite3_file*, c
8e80: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 onst void*, int
8e90: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e iAmt, sqlite3_in
8ea0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e t64 iOfst);. in
8eb0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 t (*xTruncate)(s
8ec0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 qlite3_file*, sq
8ed0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 lite3_int64 size
8ee0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 );. int (*xSync
8ef0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
8f00: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 int flags);. i
8f10: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 nt (*xFileSize)(
8f20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 sqlite3_file*, s
8f30: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 qlite3_int64 *pS
8f40: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c ize);. int (*xL
8f50: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ock)(sqlite3_fil
8f60: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 e*, int);. int
8f70: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 (*xUnlock)(sqlit
8f80: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a e3_file*, int);.
8f90: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 int (*xCheckRe
8fa0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 servedLock)(sqli
8fb0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a te3_file*, int *
8fc0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 pResOut);. int
8fd0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 (*xFileControl)(
8fe0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
8ff0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 nt op, void *pAr
9000: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 g);. int (*xSec
9010: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 torSize)(sqlite3
9020: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 _file*);. int (
9030: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 *xDeviceCharacte
9040: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 ristics)(sqlite3
9050: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 _file*);. /* Me
9060: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
9070: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f valid for versio
9080: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 n 1 */. int (*x
9090: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f ShmMap)(sqlite3_
90a0: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 file*, int iPg,
90b0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 int pgsz, int, v
90c0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b oid volatile**);
90d0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 . int (*xShmLoc
90e0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a k)(sqlite3_file*
90f0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e , int offset, in
9100: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b t n, int flags);
9110: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 . void (*xShmBa
9120: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 rrier)(sqlite3_f
9130: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ile*);. int (*x
9140: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 ShmUnmap)(sqlite
9150: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 3_file*, int del
9160: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d eteFlag);. /* M
9170: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
9180: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 valid for versi
9190: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a on 2 */. int (*
91a0: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f xFetch)(sqlite3_
91b0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 file*, sqlite3_i
91c0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 nt64 iOfst, int
91d0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 iAmt, void **pp)
91e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 ;. int (*xUnfet
91f0: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ch)(sqlite3_file
9200: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
9210: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 iOfst, void *p)
9220: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 ;. /* Methods a
9230: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 bove are valid f
9240: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a or version 3 */.
9250: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 /* Additional
9260: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 methods may be a
9270: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
9280: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f eleases */.};../
9290: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
92a0: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e tandard File Con
92b0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 trol Opcodes.**
92c0: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 KEYWORDS: {file
92d0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d control opcodes}
92e0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f {file control o
92f0: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 pcode}.**.** The
9300: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 se integer const
9310: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 ants are opcodes
9320: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f for the xFileCo
9330: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 ntrol method.**
9340: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
9350: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
9360: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b ct and for the [
9370: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
9380: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 trol()].** inter
9390: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e face..**.** <ul>
93a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
93b0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
93c0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
93d0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
93e0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 E] opcode is use
93f0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e d for debugging.
9400: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 This.** opcode
9410: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c causes the xFil
9420: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
9430: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 to write the cur
9440: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a rent state of.**
9450: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f the lock (one o
9460: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e f [SQLITE_LOCK_N
9470: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f ONE], [SQLITE_LO
9480: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b CK_SHARED],.** [
9490: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
94a0: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c RVED], [SQLITE_L
94b0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 OCK_PENDING], or
94c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 [SQLITE_LOCK_EX
94d0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 CLUSIVE]).** int
94e0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 o an integer tha
94f0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d t the pArg argum
9500: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 ent points to. T
9510: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a his capability.*
9520: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 * is used during
9530: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 testing and is
9540: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 only available w
9550: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 hen the SQLITE_T
9560: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 EST.** compile-t
9570: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 ime option is us
9580: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ed..**.** <li>[[
9590: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a SQLITE_FCNTL_SIZ
95a0: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 E_HINT]].** The
95b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 [SQLITE_FCNTL_SI
95c0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 ZE_HINT] opcode
95d0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 is used by SQLit
95e0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 e to give the VF
95f0: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e S.** layer a hin
9600: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 t of how large t
9610: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
9620: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 will grow to be
9630: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 during the.** c
9640: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 urrent transacti
9650: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 on. This hint i
9660: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 s not guaranteed
9670: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 to be accurate
9680: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 but it.** is oft
9690: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 en close. The u
96a0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 nderlying VFS mi
96b0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 ght choose to pr
96c0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 eallocate databa
96d0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 se.** file space
96e0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 based on this h
96f0: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 int in order to
9700: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 help writes to t
9710: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 he database.** f
9720: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a ile run faster..
9730: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
9740: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 4c 49 TE_FCNTL_SIZE_LI
9750: 4d 49 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 MIT]].** The [SQ
9760: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f LITE_FCNTL_SIZE_
9770: 4c 49 4d 49 54 5d 20 6f 70 63 6f 64 65 20 69 73 LIMIT] opcode is
9780: 20 75 73 65 64 20 62 79 20 69 6e 2d 6d 65 6d 6f used by in-memo
9790: 72 79 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 69 ry VFS that.** i
97a0: 6d 70 6c 65 6d 65 6e 74 73 20 5b 73 71 6c 69 74 mplements [sqlit
97b0: 65 33 5f 64 65 73 65 72 69 61 6c 69 7a 65 28 29 e3_deserialize()
97c0: 5d 20 74 6f 20 73 65 74 20 61 6e 20 75 70 70 65 ] to set an uppe
97d0: 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 r bound on the s
97e0: 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e ize.** of the in
97f0: 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
9800: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 . The argument
9810: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
9820: 61 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 a [sqlite3_int64
9830: 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 ]..** If the int
9840: 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20 eger pointed to
9850: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
9860: 6e 20 69 74 20 69 73 20 66 69 6c 6c 65 64 20 69 n it is filled i
9870: 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 63 75 n with the.** cu
9880: 72 72 65 6e 74 20 6c 69 6d 69 74 2e 20 20 4f 74 rrent limit. Ot
9890: 68 65 72 77 69 73 65 20 74 68 65 20 6c 69 6d 69 herwise the limi
98a0: 74 20 69 73 20 73 65 74 20 74 6f 20 74 68 65 20 t is set to the
98b0: 6c 61 72 67 65 72 20 6f 66 20 74 68 65 20 76 61 larger of the va
98c0: 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e lue.** of the in
98d0: 74 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f teger pointed to
98e0: 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 and the current
98f0: 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 2e 20 database size.
9900: 20 54 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 The integer.**
9910: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 73 65 pointed to is se
9920: 74 20 74 6f 20 74 68 65 20 6e 65 77 20 6c 69 6d t to the new lim
9930: 69 74 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b it..**.** <li>[[
9940: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 SQLITE_FCNTL_CHU
9950: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 NK_SIZE]].** The
9960: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 [SQLITE_FCNTL_C
9970: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 HUNK_SIZE] opcod
9980: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 e is used to req
9990: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 uest that the VF
99a0: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 S.** extends and
99b0: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 truncates the d
99c0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 atabase file in
99d0: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 chunks of a size
99e0: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 specified.** by
99f0: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 the user. The f
9a00: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 ourth argument t
9a10: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f o [sqlite3_file_
9a20: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c control()] shoul
9a30: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 d .** point to a
9a40: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 n integer (type
9a50: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 int) containing
9a60: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 the new chunk-si
9a70: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 ze to use.** for
9a80: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 the nominated d
9a90: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 atabase. Allocat
9aa0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c ing database fil
9ab0: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 e space in large
9ac0: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 .** chunks (say
9ad0: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 1MB at a time),
9ae0: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d may reduce file-
9af0: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 system fragmenta
9b00: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 tion and.** impr
9b10: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 ove performance
9b20: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e on some systems.
9b30: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
9b40: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 ITE_FCNTL_FILE_P
9b50: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 OINTER]].** The
9b60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 [SQLITE_FCNTL_FI
9b70: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f LE_POINTER] opco
9b80: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 de is used to ob
9b90: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a tain a pointer.*
9ba0: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 * to the [sqlite
9bb0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 3_file] object a
9bc0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 ssociated with a
9bd0: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 particular data
9be0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
9bf0: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 on. See also [S
9c00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 QLITE_FCNTL_JOUR
9c10: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a NAL_POINTER]..**
9c20: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
9c30: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 _FCNTL_JOURNAL_P
9c40: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 OINTER]].** The
9c50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f [SQLITE_FCNTL_JO
9c60: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f URNAL_POINTER] o
9c70: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
9c80: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 obtain a pointe
9c90: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c r.** to the [sql
9ca0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
9cb0: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 t associated wit
9cc0: 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 h the journal fi
9cd0: 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 le (either.** th
9ce0: 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 e [rollback jour
9cf0: 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 nal] or the [wri
9d00: 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 te-ahead log]) f
9d10: 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 or a particular
9d20: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
9d30: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 ection. See als
9d40: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f o [SQLITE_FCNTL_
9d50: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a FILE_POINTER]..*
9d60: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
9d70: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 E_FCNTL_SYNC_OMI
9d80: 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e TTED]].** No lon
9d90: 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a ger in use..**.*
9da0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
9db0: 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 CNTL_SYNC]].** T
9dc0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
9dd0: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 _SYNC] opcode is
9de0: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 generated inter
9df0: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 nally by SQLite
9e00: 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 and.** sent to t
9e10: 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 he VFS immediate
9e20: 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 ly before the xS
9e30: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e ync method is in
9e40: 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 voked on a.** da
9e50: 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 tabase file desc
9e60: 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 riptor. Or, if t
9e70: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 he xSync method
9e80: 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a is not invoked .
9e90: 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75 ** because the u
9ea0: 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 ser has configur
9eb0: 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a ed SQLite with .
9ec0: 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 ** [PRAGMA synch
9ed0: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 ronous | PRAGMA
9ee0: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d synchronous=OFF]
9ef0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 it is invoked i
9f00: 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 n place .** of t
9f10: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e he xSync method.
9f20: 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 In most cases,
9f30: 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 the pointer argu
9f40: 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 ment passed with
9f50: 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f .** this file-co
9f60: 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 ntrol is NULL. H
9f70: 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 owever, if the d
9f80: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 atabase file is
9f90: 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 being synced.**
9fa0: 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c as part of a mul
9fb0: 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d ti-database comm
9fc0: 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 it, the argument
9fd0: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c points to a nul
9fe0: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 -terminated.** s
9ff0: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 tring containing
a000: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
a010: 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c s master-journal
a020: 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 file name. VFSe
a030: 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f s that .** do no
a040: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e t need this sign
a050: 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 al should silent
a060: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f ly ignore this o
a070: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 pcode. Applicati
a080: 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e ons .** should n
a090: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 ot call [sqlite3
a0a0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
a0b0: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 with this opcod
a0c0: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 e as doing so ma
a0d0: 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 y .** disrupt th
a0e0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 e operation of t
a0f0: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 he specialized V
a100: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 FSes that do req
a110: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a uire it. .**.**
a120: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
a130: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 NTL_COMMIT_PHASE
a140: 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 TWO]].** The [SQ
a150: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 LITE_FCNTL_COMMI
a160: 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f T_PHASETWO] opco
a170: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 de is generated
a180: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 internally by SQ
a190: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 Lite.** and sent
a1a0: 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 to the VFS afte
a1b0: 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 r a transaction
a1c0: 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 has been committ
a1d0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a ed immediately.*
a1e0: 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 * but before the
a1f0: 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c database is unl
a200: 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 ocked. VFSes tha
a210: 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 t do not need th
a220: 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f is signal.** sho
a230: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e uld silently ign
a240: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e ore this opcode.
a250: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 Applications sh
a260: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a ould not call.**
a270: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
a280: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 ontrol()] with t
a290: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f his opcode as do
a2a0: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 ing so may disru
a2b0: 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 pt the .** opera
a2c0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 tion of the spec
a2d0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 ialized VFSes th
a2e0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 at do require it
a2f0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b . .**.** <li>[[
a300: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
a310: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 32_AV_RETRY]].**
a320: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^The [SQLITE_FC
a330: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 NTL_WIN32_AV_RET
a340: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 RY] opcode is us
a350: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 ed to configure
a360: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 automatic.** ret
a370: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e ry counts and in
a380: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 tervals for cert
a390: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 ain disk I/O ope
a3a0: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a rations for the.
a3b0: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d ** windows [VFS]
a3c0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f in order to pro
a3d0: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 vide robustness
a3e0: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 in the presence
a3f0: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 of.** anti-virus
a400: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 programs. By d
a410: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 efault, the wind
a420: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 ows VFS will ret
a430: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a ry file read,.**
a440: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 file write, and
a450: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 file delete ope
a460: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 rations up to 10
a470: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 times, with a d
a480: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 elay.** of 25 mi
a490: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 lliseconds befor
a4a0: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 e the first retr
a4b0: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 y and with the d
a4c0: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a elay increasing.
a4d0: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f ** by an additio
a4e0: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f nal 25 milliseco
a4f0: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 nds with each su
a500: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 bsequent retry.
a510: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 This.** opcode
a520: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f allows these two
a530: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 values (10 retr
a540: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 ies and 25 milli
a550: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 seconds of delay
a560: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 ).** to be adjus
a570: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 ted. The values
a580: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 are changed for
a590: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f all database co
a5a0: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 nnections.** wit
a5b0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f hin the same pro
a5c0: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d cess. The argum
a5d0: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
a5e0: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 to an array of
a5f0: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 two.** integers
a600: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20 where the first
a610: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 6e integer is the n
a620: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 ew retry count a
a630: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a nd the second.**
a640: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 integer is the
a650: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 delay. If eithe
a660: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 r integer is neg
a670: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 ative, then the
a680: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f setting.** is no
a690: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e t changed but in
a6a0: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 stead the prior
a6b0: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 value of that se
a6c0: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e tting is written
a6d0: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 .** into the arr
a6e0: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 ay entry, allowi
a6f0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 ng the current r
a700: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f etry settings to
a710: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 be.** interroga
a720: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d ted. The zDbNam
a730: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 e parameter is i
a740: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c gnored..**.** <l
a750: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
a760: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a _PERSIST_WAL]].*
a770: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
a780: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c CNTL_PERSIST_WAL
a790: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
a7a0: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 to set or query
a7b0: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 the.** persiste
a7c0: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 nt [WAL | Write
a7d0: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 Ahead Log] setti
a7e0: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c ng. By default,
a7f0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a the auxiliary.*
a800: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f * write ahead lo
a810: 67 20 28 5b 57 41 4c 20 66 69 6c 65 5d 29 20 61 g ([WAL file]) a
a820: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 nd shared memory
a830: 0a 2a 2a 20 66 69 6c 65 73 20 75 73 65 64 20 66 .** files used f
a840: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 or transaction c
a850: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 ontrol.** are au
a860: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 tomatically dele
a870: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 ted when the lat
a880: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 est connection t
a890: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a o the database.*
a8a0: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 * closes. Setti
a8b0: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 ng persistent WA
a8c0: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 L mode causes th
a8d0: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 ose files to per
a8e0: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c sist after.** cl
a8f0: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 ose. Persisting
a900: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 the files is us
a910: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 eful when other
a920: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 processes that d
a930: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 o not.** have wr
a940: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f ite permission o
a950: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 n the directory
a960: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 containing the d
a970: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e atabase file wan
a980: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 t.** to read the
a990: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
a9a0: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 as the WAL and s
a9b0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c hared memory fil
a9c0: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a es must exist.**
a9d0: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 in order for th
a9e0: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 e database to be
a9f0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 readable. The
aa00: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
aa10: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
aa20: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
aa30: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 for this opcode
aa40: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e should be a poin
aa50: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
aa60: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 r..** That integ
aa70: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 er is 0 to disab
aa80: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 le persistent WA
aa90: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 L mode or 1 to e
aaa0: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 nable persistent
aab0: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 .** WAL mode. I
aac0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 f the integer is
aad0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 -1, then it is
aae0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 overwritten with
aaf0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
ab00: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 WAL persistence
ab10: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c setting..**.** <
ab20: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
ab30: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 L_POWERSAFE_OVER
ab40: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 WRITE]].** ^The
ab50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f [SQLITE_FCNTL_PO
ab60: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 WERSAFE_OVERWRIT
ab70: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 E] opcode is use
ab80: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 d to set or quer
ab90: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 y the.** persist
aba0: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f ent "powersafe-o
abb0: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 verwrite" or "PS
abc0: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 OW" setting. Th
abd0: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a e PSOW setting.*
abe0: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 * determines the
abf0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 [SQLITE_IOCAP_P
ac00: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
ac10: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a TE] bit of the.*
ac20: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 * xDeviceCharact
ac30: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 eristics methods
ac40: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 . The fourth par
ac50: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 ameter to.** [sq
ac60: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
ac70: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f ol()] for this o
ac80: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 pcode should be
ac90: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
aca0: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 integer..** That
acb0: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f integer is 0 to
acc0: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 disable zero-da
acd0: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 mage mode or 1 t
ace0: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 o enable zero-da
acf0: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 mage.** mode. I
ad00: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 f the integer is
ad10: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 -1, then it is
ad20: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 overwritten with
ad30: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
ad40: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 zero-damage mode
ad50: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 setting..**.**
ad60: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
ad70: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a TL_OVERWRITE]].*
ad80: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
ad90: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 CNTL_OVERWRITE]
ada0: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 opcode is invoke
adb0: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 d by SQLite afte
adc0: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 r opening.** a w
add0: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e rite transaction
ade0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
adf0: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 t, unless it is
ae00: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 rolled back for
ae10: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 some.** reason,
ae20: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 the entire datab
ae30: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 ase file will be
ae40: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 overwritten by
ae50: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 the current .**
ae60: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 transaction. Thi
ae70: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 s is used by VAC
ae80: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a UUM operations..
ae90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
aea0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 TE_FCNTL_VFSNAME
aeb0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 ]].** ^The [SQLI
aec0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 TE_FCNTL_VFSNAME
aed0: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 ] opcode can be
aee0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 used to obtain t
aef0: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 he names of.** a
af00: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 ll [VFSes] in th
af10: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 e VFS stack. Th
af20: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 e names are of a
af30: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 ll VFS shims and
af40: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f the.** final bo
af50: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 ttom-level VFS a
af60: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 re written into
af70: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
af80: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 from .** [sqlite
af90: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 3_malloc()] and
afa0: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 the result is st
afb0: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 ored in the char
afc0: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 * variable.** th
afd0: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 at the fourth pa
afe0: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 rameter of [sqli
aff0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
b000: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a ()] points to..*
b010: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 * The caller is
b020: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 responsible for
b030: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f freeing the memo
b040: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 ry when done. A
b050: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 s with.** all fi
b060: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f le-control actio
b070: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 ns, there is no
b080: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 guarantee that t
b090: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c his will actuall
b0a0: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 y.** do anything
b0b0: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c . Callers shoul
b0c0: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 d initialize the
b0d0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 char* variable
b0e0: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 to a NULL.** poi
b0f0: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 nter in case thi
b100: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 s file-control i
b110: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 s not implemente
b120: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f d. This file-co
b130: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 ntrol.** is inte
b140: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 nded for diagnos
b150: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a tic use only..**
b160: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
b170: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 _FCNTL_VFS_POINT
b180: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ER]].** ^The [SQ
b190: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 LITE_FCNTL_VFS_P
b1a0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 OINTER] opcode f
b1b0: 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74 inds a pointer t
b1c0: 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a o the top-level.
b1d0: 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65 ** [VFSes] curre
b1e0: 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 ntly in use. ^(
b1f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69 The argument X i
b200: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c n.** sqlite3_fil
b210: 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c e_control(db,SQL
b220: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f ITE_FCNTL_VFS_PO
b230: 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65 INTER,X) must be
b240: 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71 .** of type "[sq
b250: 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 lite3_vfs] **".
b260: 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69 This opcodes wi
b270: 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 ll set *X.** to
b280: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
b290: 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 top-level VFS.)
b2a0: 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 ^.** ^When there
b2b0: 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 are multiple VF
b2c0: 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73 S shims in the s
b2d0: 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 tack, this opcod
b2e0: 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 e finds the.** u
b2f0: 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f pper-most shim o
b300: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b nly..**.** <li>[
b310: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
b320: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 AGMA]].** ^Whene
b330: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 ver a [PRAGMA] s
b340: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 tatement is pars
b350: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 ed, an [SQLITE_F
b360: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a CNTL_PRAGMA] .**
b370: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 file control is
b380: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 sent to the ope
b390: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d n [sqlite3_file]
b3a0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f object correspo
b3b0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 nding.** to the
b3c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f database file to
b3d0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d which the pragm
b3e0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 a statement refe
b3f0: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e rs. ^The argumen
b400: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c t.** to the [SQL
b410: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
b420: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 ] file control i
b430: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a s an array of.**
b440: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
b450: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e ings (char**) in
b460: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e which the secon
b470: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 d element of the
b480: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 array.** is the
b490: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 name of the pra
b4a0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 gma and the thir
b4b0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 d element is the
b4c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
b4d0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 .** pragma or NU
b4e0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 LL if the pragma
b4f0: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 has no argument
b500: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 . ^The handler
b510: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 for an.** [SQLIT
b520: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
b530: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e file control can
b540: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 optionally make
b550: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 the first eleme
b560: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 nt.** of the cha
b570: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 r** argument poi
b580: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f nt to a string o
b590: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
b5a0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d lite3_mprintf()]
b5b0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 .** or the equiv
b5c0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 alent and that s
b5d0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d tring will becom
b5e0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 e the result of
b5f0: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a the pragma or.**
b600: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
b610: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 ge if the pragma
b620: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a fails. ^If the.
b630: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c ** [SQLITE_FCNTL
b640: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
b650: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 ntrol returns [S
b660: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c QLITE_NOTFOUND],
b670: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a then normal .**
b680: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 [PRAGMA] proces
b690: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 sing continues.
b6a0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 ^If the [SQLITE
b6b0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a _FCNTL_PRAGMA].*
b6c0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 * file control r
b6d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
b6e0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 K], then the par
b6f0: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 ser assumes that
b700: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 the.** VFS has
b710: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 handled the PRAG
b720: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 MA itself and th
b730: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 e parser generat
b740: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 es a no-op.** pr
b750: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
b760: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e if result strin
b770: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 g is NULL, or th
b780: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 at returns a cop
b790: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 y.** of the resu
b7a0: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65 lt string if the
b7b0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e string is non-N
b7c0: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ULL..** ^If the
b7d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
b7e0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 AGMA] file contr
b7f0: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e ol returns.** an
b800: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 y result code ot
b810: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
b820: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f _OK] or [SQLITE_
b830: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 NOTFOUND], that
b840: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 means.** that th
b850: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 e VFS encountere
b860: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 d an error while
b870: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 handling the [P
b880: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a RAGMA] and the.*
b890: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 * compilation of
b8a0: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c the PRAGMA fail
b8b0: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e s with an error.
b8c0: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ^The [SQLITE_F
b8d0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 CNTL_PRAGMA].**
b8e0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 file control occ
b8f0: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e urs at the begin
b900: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 ning of pragma s
b910: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 tatement analysi
b920: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 s and so.** it i
b930: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 s able to overri
b940: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 de built-in [PRA
b950: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e GMA] statements.
b960: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
b970: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 ITE_FCNTL_BUSYHA
b980: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 NDLER]].** ^The
b990: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 [SQLITE_FCNTL_BU
b9a0: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 SYHANDLER].** fi
b9b0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 le-control may b
b9c0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c e invoked by SQL
b9d0: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 ite on the datab
b9e0: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a ase file handle.
b9f0: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 ** shortly after
ba00: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e it is opened in
ba10: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 order to provid
ba20: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 e a custom VFS w
ba30: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f ith access.** to
ba40: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 the connections
ba50: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 busy-handler ca
ba60: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 llback. The argu
ba70: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 ment is of type
ba80: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 (void **).** - a
ba90: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 n array of two (
baa0: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 void *) values.
bab0: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 The first (void
bac0: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e *) actually poin
bad0: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 ts.** to a funct
bae0: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 ion of type (int
baf0: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 (*)(void *)). I
bb00: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b n order to invok
bb10: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e e the connection
bb20: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 s.** busy-handle
bb30: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e r, this function
bb40: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b should be invok
bb50: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f ed with the seco
bb60: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a nd (void *) in.*
bb70: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74 * the array as t
bb80: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 he only argument
bb90: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 . If it returns
bba0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 non-zero, then t
bbb0: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 he operation.**
bbc0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 should be retrie
bbd0: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 d. If it returns
bbe0: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f zero, the custo
bbf0: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 m VFS should aba
bc00: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 ndon the.** curr
bc10: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a ent operation..*
bc20: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
bc30: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 E_FCNTL_TEMPFILE
bc40: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 NAME]].** ^Appli
bc50: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b cation can invok
bc60: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 e the [SQLITE_FC
bc70: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 NTL_TEMPFILENAME
bc80: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a ] file-control.*
bc90: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 * to have SQLite
bca0: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 generate a.** t
bcb0: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d emporary filenam
bcc0: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 e using the same
bcd0: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 algorithm that
bce0: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 is followed to g
bcf0: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f enerate.** tempo
bd00: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 rary filenames f
bd10: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 or TEMP tables a
bd20: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 nd other interna
bd30: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 l uses. The.**
bd40: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
bd50: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 be a char** whic
bd60: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 h will be filled
bd70: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 with the filena
bd80: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e me.** written in
bd90: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
bda0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
bdb0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 _malloc()]. The
bdc0: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a caller should.*
bdd0: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 * invoke [sqlite
bde0: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 3_free()] on the
bdf0: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 result to avoid
be00: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a a memory leak..
be10: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
be20: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 TE_FCNTL_MMAP_SI
be30: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ZE]].** The [SQL
be40: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 ITE_FCNTL_MMAP_S
be50: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f IZE] file contro
be60: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 l is used to que
be70: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a ry or set the.**
be80: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
be90: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69 of bytes that wi
bea0: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d ll be used for m
beb0: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f emory-mapped I/O
bec0: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e ..** The argumen
bed0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
bee0: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 o a value of typ
bef0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 e sqlite3_int64
bf00: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 that.** is an ad
bf10: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e visory maximum n
bf20: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
bf30: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 n the file to me
bf40: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a mory map. The.*
bf50: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 * pointer is ove
bf60: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 rwritten with th
bf70: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 e old value. Th
bf80: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 e limit is not c
bf90: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 hanged if.** the
bfa0: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c value originall
bfb0: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 y pointed to is
bfc0: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f negative, and so
bfd0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d the current lim
bfe0: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 it .** can be qu
bff0: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 eried by passing
c000: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f in a pointer to
c010: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 a negative numb
c020: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c er. This.** fil
c030: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 e-control is use
c040: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 d internally to
c050: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d implement [PRAGM
c060: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a A mmap_size]..**
c070: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
c080: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a _FCNTL_TRACE]].*
c090: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
c0a0: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 NTL_TRACE] file
c0b0: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 control provides
c0c0: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d advisory inform
c0d0: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 ation.** to the
c0e0: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 VFS about what t
c0f0: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 he higher layers
c100: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 of the SQLite s
c110: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a tack are doing..
c120: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e ** This file con
c130: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 trol is used by
c140: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 some VFS activit
c150: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 y tracing [shims
c160: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 ]..** The argume
c170: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 nt is a zero-ter
c180: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 minated string.
c190: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 Higher layers i
c1a0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 n the.** SQLite
c1b0: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 stack may genera
c1c0: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 te instances of
c1d0: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f this file contro
c1e0: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c l if.** the [SQL
c1f0: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 ITE_USE_FCNTL_TR
c200: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d ACE] compile-tim
c210: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 e option is enab
c220: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b led..**.** <li>[
c230: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 [SQLITE_FCNTL_HA
c240: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 S_MOVED]].** The
c250: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 [SQLITE_FCNTL_H
c260: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 AS_MOVED] file c
c270: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 ontrol interpret
c280: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 s its argument a
c290: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 s a.** pointer t
c2a0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 o an integer and
c2b0: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f it writes a boo
c2c0: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 lean into that i
c2d0: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 nteger depending
c2e0: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f .** on whether o
c2f0: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 r not the file h
c300: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c as been renamed,
c310: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 moved, or delet
c320: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 ed since it.** w
c330: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e as first opened.
c340: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
c350: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
c360: 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 GET_HANDLE]].**
c370: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
c380: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 L_WIN32_GET_HAND
c390: 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 LE] opcode can b
c3a0: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e e used to obtain
c3b0: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 the.** underlyi
c3c0: 6e 67 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 ng native file h
c3d0: 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64 andle associated
c3e0: 20 77 69 74 68 20 61 20 66 69 6c 65 20 68 61 6e with a file han
c3f0: 64 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65 0a dle. This file.
c400: 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 ** control inter
c410: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 prets its argume
c420: 6e 74 20 61 73 20 61 20 70 6f 69 6e 74 65 72 20 nt as a pointer
c430: 74 6f 20 61 20 6e 61 74 69 76 65 20 66 69 6c 65 to a native file
c440: 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 handle and.** w
c450: 72 69 74 65 73 20 74 68 65 20 72 65 73 75 6c 74 rites the result
c460: 69 6e 67 20 76 61 6c 75 65 20 74 68 65 72 65 2e ing value there.
c470: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
c480: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
c490: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 SET_HANDLE]].**
c4a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
c4b0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 L_WIN32_SET_HAND
c4c0: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 LE] opcode is us
c4d0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 ed for debugging
c4e0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 . This.** opcod
c4f0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 e causes the xFi
c500: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
c510: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c to swap the fil
c520: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 e handle with th
c530: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 e one.** pointed
c540: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 to by the pArg
c550: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 argument. This
c560: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 capability is us
c570: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
c580: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 g.** and only ne
c590: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 eds to be suppor
c5a0: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f ted when SQLITE_
c5b0: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e TEST is defined.
c5c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
c5d0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c ITE_FCNTL_WAL_BL
c5e0: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 OCK]].** The [SQ
c5f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 LITE_FCNTL_WAL_B
c600: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 LOCK] is a signa
c610: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 l to the VFS lay
c620: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 er that it might
c630: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 .** be advantage
c640: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 ous to block on
c650: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 the next WAL loc
c660: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 k if the lock is
c670: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 not immediately
c680: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 .** available.
c690: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 The WAL subsyste
c6a0: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69 m issues this si
c6b0: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 gnal during rare
c6c0: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 .** circumstance
c6d0: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 s in order to fi
c6e0: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 x a problem with
c6f0: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 priority invers
c700: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 ion..** Applicat
c710: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e ions should <em>
c720: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 not</em> use thi
c730: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a s file-control..
c740: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
c750: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d TE_FCNTL_ZIPVFS]
c760: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
c770: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f _FCNTL_ZIPVFS] o
c780: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 pcode is impleme
c790: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f nted by zipvfs o
c7a0: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a nly. All other.*
c7b0: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 * VFS should ret
c7c0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f urn SQLITE_NOTFO
c7d0: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63 UND for this opc
c7e0: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ode..**.** <li>[
c7f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 [SQLITE_FCNTL_RB
c800: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 U]].** The [SQLI
c810: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 TE_FCNTL_RBU] op
c820: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e code is implemen
c830: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69 ted by the speci
c840: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a al VFS used by.*
c850: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73 * the RBU extens
c860: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f ion only. All o
c870: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20 ther VFS should
c880: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f return SQLITE_NO
c890: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 TFOUND for.** th
c8a0: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a is opcode. .**.
c8b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
c8c0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d FCNTL_BEGIN_ATOM
c8d0: 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49 66 IC_WRITE]].** If
c8e0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e the [SQLITE_FCN
c8f0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f TL_BEGIN_ATOMIC_
c900: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 72 65 WRITE] opcode re
c910: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2c turns SQLITE_OK,
c920: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 66 69 6c then.** the fil
c930: 65 20 64 65 73 63 72 69 70 74 6f 72 20 69 73 20 e descriptor is
c940: 70 6c 61 63 65 64 20 69 6e 20 22 62 61 74 63 68 placed in "batch
c950: 20 77 72 69 74 65 20 6d 6f 64 65 22 2c 20 77 68 write mode", wh
c960: 69 63 68 0a 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c ich.** means all
c970: 20 73 75 62 73 65 71 75 65 6e 74 20 77 72 69 74 subsequent writ
c980: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 69 6c e operations wil
c990: 6c 20 62 65 20 64 65 66 65 72 72 65 64 20 61 6e l be deferred an
c9a0: 64 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63 d done.** atomic
c9b0: 61 6c 6c 79 20 61 74 20 74 68 65 20 6e 65 78 74 ally at the next
c9c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 [SQLITE_FCNTL_C
c9d0: 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 OMMIT_ATOMIC_WRI
c9e0: 54 45 5d 2e 20 20 53 79 73 74 65 6d 73 0a 2a 2a TE]. Systems.**
c9f0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 73 75 70 that do not sup
ca00: 70 6f 72 74 20 62 61 74 63 68 20 61 74 6f 6d 69 port batch atomi
ca10: 63 20 77 72 69 74 65 73 20 77 69 6c 6c 20 72 65 c writes will re
ca20: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 turn SQLITE_NOTF
ca30: 4f 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 OUND..** ^Follow
ca40: 69 6e 67 20 61 20 73 75 63 63 65 73 73 66 75 6c ing a successful
ca50: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 SQLITE_FCNTL_BE
ca60: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 GIN_ATOMIC_WRITE
ca70: 20 61 6e 64 20 70 72 69 6f 72 20 74 6f 0a 2a 2a and prior to.**
ca80: 20 74 68 65 20 63 6c 6f 73 69 6e 67 20 5b 53 51 the closing [SQ
ca90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 LITE_FCNTL_COMMI
caa0: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 T_ATOMIC_WRITE]
cab0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 or.** [SQLITE_FC
cac0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f NTL_ROLLBACK_ATO
cad0: 4d 49 43 5f 57 52 49 54 45 5d 2c 20 53 51 4c 69 MIC_WRITE], SQLi
cae0: 74 65 20 77 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 te will make.**
caf0: 6e 6f 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 no VFS interface
cb00: 20 63 61 6c 6c 73 20 6f 6e 20 74 68 65 20 73 61 calls on the sa
cb10: 6d 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 me [sqlite3_file
cb20: 5d 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f ] file descripto
cb30: 72 0a 2a 2a 20 65 78 63 65 70 74 20 66 6f 72 20 r.** except for
cb40: 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 78 57 72 calls to the xWr
cb50: 69 74 65 20 6d 65 74 68 6f 64 20 61 6e 64 20 74 ite method and t
cb60: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 he xFileControl
cb70: 6d 65 74 68 6f 64 0a 2a 2a 20 77 69 74 68 20 5b method.** with [
cb80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a SQLITE_FCNTL_SIZ
cb90: 45 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c E_HINT]..**.** <
cba0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
cbb0: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f L_COMMIT_ATOMIC_
cbc0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b WRITE]].** The [
cbd0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d SQLITE_FCNTL_COM
cbe0: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 MIT_ATOMIC_WRITE
cbf0: 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 ] opcode causes
cc00: 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 all write.** ope
cc10: 72 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 rations since th
cc20: 65 20 70 72 65 76 69 6f 75 73 20 73 75 63 63 65 e previous succe
cc30: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a ssful call to .*
cc40: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f * [SQLITE_FCNTL_
cc50: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 BEGIN_ATOMIC_WRI
cc60: 54 45 5d 20 74 6f 20 62 65 20 70 65 72 66 6f 72 TE] to be perfor
cc70: 6d 65 64 20 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a med atomically..
cc80: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e ** This file con
cc90: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 trol returns [SQ
cca0: 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6e 64 20 LITE_OK] if and
ccb0: 6f 6e 6c 79 20 69 66 20 74 68 65 20 77 72 69 74 only if the writ
ccc0: 65 73 20 77 65 72 65 0a 2a 2a 20 61 6c 6c 20 70 es were.** all p
ccd0: 65 72 66 6f 72 6d 65 64 20 73 75 63 63 65 73 73 erformed success
cce0: 66 75 6c 6c 79 20 61 6e 64 20 68 61 76 65 20 62 fully and have b
ccf0: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 74 6f een committed to
cd00: 20 70 65 72 73 69 73 74 65 6e 74 20 73 74 6f 72 persistent stor
cd10: 61 67 65 2e 0a 2a 2a 20 5e 52 65 67 61 72 64 6c age..** ^Regardl
cd20: 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
cd30: 72 20 6e 6f 74 20 69 74 20 69 73 20 73 75 63 63 r not it is succ
cd40: 65 73 73 66 75 6c 2c 20 74 68 69 73 20 66 69 6c essful, this fil
cd50: 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 0a e control takes.
cd60: 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 ** the file desc
cd70: 72 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 riptor out of ba
cd80: 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 20 73 tch write mode s
cd90: 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65 o that all subse
cda0: 71 75 65 6e 74 0a 2a 2a 20 77 72 69 74 65 20 6f quent.** write o
cdb0: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e perations are in
cdc0: 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 dependent..** ^S
cdd0: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 QLite will never
cde0: 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 invoke SQLITE_F
cdf0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d CNTL_COMMIT_ATOM
ce00: 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 IC_WRITE without
ce10: 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 .** a prior succ
ce20: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
ce30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 SQLITE_FCNTL_BEG
ce40: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d IN_ATOMIC_WRITE]
ce50: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
ce60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 LITE_FCNTL_ROLLB
ce70: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 ACK_ATOMIC_WRITE
ce80: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
ce90: 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b E_FCNTL_ROLLBACK
cea0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f _ATOMIC_WRITE] o
ceb0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c pcode causes all
cec0: 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 write.** operat
ced0: 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 ions since the p
cee0: 72 65 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 revious successf
cef0: 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b ul call to .** [
cf00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 SQLITE_FCNTL_BEG
cf10: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d IN_ATOMIC_WRITE]
cf20: 20 74 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 to be rolled ba
cf30: 63 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c ck..** ^This fil
cf40: 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 20 e control takes
cf50: 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 the file descrip
cf60: 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 tor out of batch
cf70: 20 77 72 69 74 65 20 6d 6f 64 65 0a 2a 2a 20 73 write mode.** s
cf80: 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65 o that all subse
cf90: 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72 quent write oper
cfa0: 61 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 ations are indep
cfb0: 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 endent..** ^SQLi
cfc0: 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e te will never in
cfd0: 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 voke SQLITE_FCNT
cfe0: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 L_ROLLBACK_ATOMI
cff0: 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a C_WRITE without.
d000: 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 ** a prior succe
d010: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 ssful call to [S
d020: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 QLITE_FCNTL_BEGI
d030: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e N_ATOMIC_WRITE].
d040: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
d050: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 ITE_FCNTL_LOCK_T
d060: 49 4d 45 4f 55 54 5d 5d 0a 2a 2a 20 54 68 65 20 IMEOUT]].** The
d070: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f [SQLITE_FCNTL_LO
d080: 43 4b 5f 54 49 4d 45 4f 55 54 5d 20 6f 70 63 6f CK_TIMEOUT] opco
d090: 64 65 20 63 61 75 73 65 73 20 61 74 74 65 6d 70 de causes attemp
d0a0: 74 73 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 ts to obtain.**
d0b0: 61 20 66 69 6c 65 20 6c 6f 63 6b 20 75 73 69 6e a file lock usin
d0c0: 67 20 74 68 65 20 78 4c 6f 63 6b 20 6f 72 20 78 g the xLock or x
d0d0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 73 20 ShmLock methods
d0e0: 6f 66 20 74 68 65 20 56 46 53 20 74 6f 20 77 61 of the VFS to wa
d0f0: 69 74 0a 2a 2a 20 66 6f 72 20 75 70 20 74 6f 20 it.** for up to
d100: 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 M milliseconds b
d110: 65 66 6f 72 65 20 66 61 69 6c 69 6e 67 2c 20 77 efore failing, w
d120: 68 65 72 65 20 4d 20 69 73 20 74 68 65 20 73 69 here M is the si
d130: 6e 67 6c 65 20 0a 2a 2a 20 75 6e 73 69 67 6e 65 ngle .** unsigne
d140: 64 20 69 6e 74 65 67 65 72 20 70 61 72 61 6d 65 d integer parame
d150: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ter..**.** <li>[
d160: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 [SQLITE_FCNTL_DA
d170: 54 41 5f 56 45 52 53 49 4f 4e 5d 5d 0a 2a 2a 20 TA_VERSION]].**
d180: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
d190: 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20 L_DATA_VERSION]
d1a0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
d1b0: 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 o detect changes
d1c0: 20 74 6f 0a 2a 2a 20 61 20 64 61 74 61 62 61 73 to.** a databas
d1d0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 61 72 67 e file. The arg
d1e0: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
d1f0: 65 72 20 74 6f 20 61 20 33 32 2d 62 69 74 20 75 er to a 32-bit u
d200: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e nsigned integer.
d210: 0a 2a 2a 20 54 68 65 20 22 64 61 74 61 20 76 65 .** The "data ve
d220: 72 73 69 6f 6e 22 20 66 6f 72 20 74 68 65 20 70 rsion" for the p
d230: 61 67 65 72 20 69 73 20 77 72 69 74 74 65 6e 20 ager is written
d240: 69 6e 74 6f 20 74 68 65 20 70 6f 69 6e 74 65 72 into the pointer
d250: 2e 20 20 54 68 65 0a 2a 2a 20 22 64 61 74 61 20 . The.** "data
d260: 76 65 72 73 69 6f 6e 22 20 63 68 61 6e 67 65 73 version" changes
d270: 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 63 68 whenever any ch
d280: 61 6e 67 65 20 6f 63 63 75 72 73 20 74 6f 20 74 ange occurs to t
d290: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
d2a0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c .** database fil
d2b0: 65 2c 20 65 69 74 68 65 72 20 74 68 72 6f 75 67 e, either throug
d2c0: 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 h SQL statements
d2d0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 on the same dat
d2e0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
d2f0: 69 6f 6e 20 6f 72 20 74 68 72 6f 75 67 68 20 74 ion or through t
d300: 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 6f 6d 6d ransactions comm
d310: 69 74 74 65 64 20 62 79 20 73 65 70 61 72 61 74 itted by separat
d320: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f e database.** co
d330: 6e 6e 65 63 74 69 6f 6e 73 20 70 6f 73 73 69 62 nnections possib
d340: 6c 79 20 69 6e 20 6f 74 68 65 72 20 70 72 6f 63 ly in other proc
d350: 65 73 73 65 73 2e 20 54 68 65 20 5b 73 71 6c 69 esses. The [sqli
d360: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
d370: 73 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 s()].** interfac
d380: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
d390: 20 66 69 6e 64 20 69 66 20 61 6e 79 20 64 61 74 find if any dat
d3a0: 61 62 61 73 65 20 6f 6e 20 74 68 65 20 63 6f 6e abase on the con
d3b0: 6e 65 63 74 69 6f 6e 20 68 61 73 20 63 68 61 6e nection has chan
d3c0: 67 65 64 2c 0a 2a 2a 20 62 75 74 20 74 68 61 74 ged,.** but that
d3d0: 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 70 6f interface respo
d3e0: 6e 64 73 20 74 6f 20 63 68 61 6e 67 65 73 20 6f nds to changes o
d3f0: 6e 20 54 45 4d 50 20 61 73 20 77 65 6c 6c 20 61 n TEMP as well a
d400: 73 20 4d 41 49 4e 20 61 6e 64 20 64 6f 65 73 0a s MAIN and does.
d410: 2a 2a 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 ** not provide a
d420: 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20 64 65 mechanism to de
d430: 74 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 20 tect changes to
d440: 4d 41 49 4e 20 6f 6e 6c 79 2e 20 20 41 6c 73 6f MAIN only. Also
d450: 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 , the.** [sqlite
d460: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
d470: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 )] interface res
d480: 70 6f 6e 64 73 20 74 6f 20 69 6e 74 65 72 6e 61 ponds to interna
d490: 6c 20 63 68 61 6e 67 65 73 20 6f 6e 6c 79 20 61 l changes only a
d4a0: 6e 64 0a 2a 2a 20 6f 6d 69 74 73 20 63 68 61 6e nd.** omits chan
d4b0: 67 65 73 20 6d 61 64 65 20 62 79 20 6f 74 68 65 ges made by othe
d4c0: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 r database conne
d4d0: 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 ctions. The.**
d4e0: 5b 50 52 41 47 4d 41 20 64 61 74 61 5f 76 65 72 [PRAGMA data_ver
d4f0: 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20 70 72 sion] command pr
d500: 6f 76 69 64 65 20 61 20 6d 65 63 68 61 6e 69 73 ovide a mechanis
d510: 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e m to detect chan
d520: 67 65 73 20 74 6f 0a 2a 2a 20 61 20 73 69 6e 67 ges to.** a sing
d530: 6c 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 le attached data
d540: 62 61 73 65 20 74 68 61 74 20 6f 63 63 75 72 20 base that occur
d550: 64 75 65 20 74 6f 20 6f 74 68 65 72 20 64 61 74 due to other dat
d560: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
d570: 73 2c 0a 2a 2a 20 62 75 74 20 6f 6d 69 74 73 20 s,.** but omits
d580: 63 68 61 6e 67 65 73 20 69 6d 70 6c 65 6d 65 6e changes implemen
d590: 74 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62 ted by the datab
d5a0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f ase connection o
d5b0: 6e 20 77 68 69 63 68 20 69 74 20 69 73 0a 2a 2a n which it is.**
d5c0: 20 63 61 6c 6c 65 64 2e 20 20 54 68 69 73 20 66 called. This f
d5d0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 74 ile control is t
d5e0: 68 65 20 6f 6e 6c 79 20 6d 65 63 68 61 6e 69 73 he only mechanis
d5f0: 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e m to detect chan
d600: 67 65 73 20 74 68 61 74 0a 2a 2a 20 68 61 70 70 ges that.** happ
d610: 65 6e 20 65 69 74 68 65 72 20 69 6e 74 65 72 6e en either intern
d620: 61 6c 6c 79 20 6f 72 20 65 78 74 65 72 6e 61 6c ally or external
d630: 6c 79 20 61 6e 64 20 74 68 61 74 20 61 72 65 20 ly and that are
d640: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a associated with.
d650: 2a 2a 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 ** a particular
d660: 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
d670: 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 e..** </ul>.*/.#
d680: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
d690: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 NTL_LOCKSTATE
d6a0: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 1.#d
d6b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
d6c0: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TL_GET_LOCKPROXY
d6d0: 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65 FILE 2.#de
d6e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
d6f0: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 L_SET_LOCKPROXYF
d700: 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66 ILE 3.#def
d710: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
d720: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 _LAST_ERRNO
d730: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 4.#defi
d740: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
d750: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 SIZE_HINT
d760: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 5.#defin
d770: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 e SQLITE_FCNTL_C
d780: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 HUNK_SIZE
d790: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 6.#define
d7a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 SQLITE_FCNTL_FI
d7b0: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 LE_POINTER
d7c0: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 7.#define
d7d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e SQLITE_FCNTL_SYN
d7e0: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 C_OMITTED
d7f0: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 8.#define S
d800: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 QLITE_FCNTL_WIN3
d810: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 2_AV_RETRY
d820: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 9.#define SQ
d830: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 LITE_FCNTL_PERSI
d840: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 ST_WAL
d850: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 10.#define SQL
d860: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 ITE_FCNTL_OVERWR
d870: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ITE
d880: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 11.#define SQLI
d890: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 TE_FCNTL_VFSNAME
d8a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
d8b0: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 12.#define SQLIT
d8c0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 E_FCNTL_POWERSAF
d8d0: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 E_OVERWRITE 1
d8e0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
d8f0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 _FCNTL_PRAGMA
d900: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 14
d910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d920: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 FCNTL_BUSYHANDLE
d930: 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a R 15.
d940: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
d950: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d CNTL_TEMPFILENAM
d960: 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 E 16.#
d970: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
d980: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 NTL_MMAP_SIZE
d990: 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 18.#d
d9a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
d9b0: 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 TL_TRACE
d9c0: 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 19.#de
d9d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
d9e0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 L_HAS_MOVED
d9f0: 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 20.#def
da00: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
da10: 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 _SYNC
da20: 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 21.#defi
da30: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
da40: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 COMMIT_PHASETWO
da50: 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 22.#defin
da60: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 e SQLITE_FCNTL_W
da70: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 IN32_SET_HANDLE
da80: 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 23.#define
da90: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 SQLITE_FCNTL_WA
daa0: 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 L_BLOCK
dab0: 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20 24.#define
dac0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 SQLITE_FCNTL_ZIP
dad0: 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20 20 VFS
dae0: 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53 25.#define S
daf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 QLITE_FCNTL_RBU
db00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
db10: 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51 26.#define SQ
db20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 LITE_FCNTL_VFS_P
db30: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 OINTER
db40: 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 27.#define SQL
db50: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 ITE_FCNTL_JOURNA
db60: 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 L_POINTER
db70: 20 32 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 28.#define SQLI
db80: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 TE_FCNTL_WIN32_G
db90: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 ET_HANDLE
dba0: 32 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 29.#define SQLIT
dbb0: 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 E_FCNTL_PDB
dbc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 3
dbd0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
dbe0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f _FCNTL_BEGIN_ATO
dbf0: 4d 49 43 5f 57 52 49 54 45 20 20 20 20 20 33 31 MIC_WRITE 31
dc00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
dc10: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f FCNTL_COMMIT_ATO
dc20: 4d 49 43 5f 57 52 49 54 45 20 20 20 20 33 32 0a MIC_WRITE 32.
dc30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
dc40: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 CNTL_ROLLBACK_AT
dc50: 4f 4d 49 43 5f 57 52 49 54 45 20 20 33 33 0a 23 OMIC_WRITE 33.#
dc60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
dc70: 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 NTL_LOCK_TIMEOUT
dc80: 20 20 20 20 20 20 20 20 20 20 20 33 34 0a 23 64 34.#d
dc90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
dca0: 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 20 TL_DATA_VERSION
dcb0: 20 20 20 20 20 20 20 20 20 20 33 35 0a 23 64 65 35.#de
dcc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
dcd0: 4c 5f 53 49 5a 45 5f 4c 49 4d 49 54 20 20 20 20 L_SIZE_LIMIT
dce0: 20 20 20 20 20 20 20 20 20 33 36 0a 0a 2f 2a 20 36../*
dcf0: 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 deprecated names
dd00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
dd10: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TE_GET_LOCKPROXY
dd20: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 FILE SQLITE
dd30: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 _FCNTL_GET_LOCKP
dd40: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 ROXYFILE.#define
dd50: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b SQLITE_SET_LOCK
dd60: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 PROXYFILE S
dd70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f QLITE_FCNTL_SET_
dd80: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 LOCKPROXYFILE.#d
dd90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 efine SQLITE_LAS
dda0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 T_ERRNO
ddb0: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c SQLITE_FCNTL
ddc0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a _LAST_ERRNO.../*
ddd0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 .** CAPI3REF: Mu
dde0: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a tex Handle.**.**
ddf0: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c The mutex modul
de00: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 e within SQLite
de10: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 defines [sqlite3
de20: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e _mutex] to be an
de30: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 .** abstract typ
de40: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 e for a mutex ob
de50: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 ject. The SQLit
de60: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f e core never loo
de70: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 ks.** at the int
de80: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 ernal representa
de90: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 tion of an [sqli
dea0: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 te3_mutex]. It
deb0: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 only.** deals wi
dec0: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 th pointers to t
ded0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
dee0: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a x] object..**.**
def0: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 Mutexes are cre
df00: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ated using [sqli
df10: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 te3_mutex_alloc(
df20: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 )]..*/.typedef s
df30: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 truct sqlite3_mu
df40: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 tex sqlite3_mute
df50: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 x;../*.** CAPI3R
df60: 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 EF: Loadable Ext
df70: 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a ension Thunk.**.
df80: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** A pointer to
df90: 74 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74 the opaque sqlit
dfa0: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 e3_api_routines
dfb0: 73 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73 structure is pas
dfc0: 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 sed as.** the th
dfd0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
dfe0: 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 entry points of
dff0: 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e [loadable exten
e000: 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a sions]. This.**
e010: 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 structure must
e020: 62 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20 be typedefed in
e030: 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 order to work ar
e040: 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 ound compiler wa
e050: 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d rnings.** on som
e060: 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a e platforms..*/.
e070: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
e080: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 qlite3_api_routi
e090: 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f nes sqlite3_api_
e0a0: 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a routines;../*.**
e0b0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e CAPI3REF: OS In
e0c0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a terface Object.*
e0d0: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
e0e0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
e0f0: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e vfs object defin
e100: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
e110: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 between.** the
e120: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 SQLite core and
e130: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f the underlying o
e140: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e perating system.
e150: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 The "vfs".** i
e160: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
e170: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 e object stands
e180: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c for "virtual fil
e190: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a e system". See.
e1a0: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 ** the [VFS | VF
e1b0: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d S documentation]
e1c0: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 for further inf
e1d0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
e1e0: 54 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63 The VFS interfac
e1f0: 65 20 69 73 20 73 6f 6d 65 74 69 6d 65 73 20 65 e is sometimes e
e200: 78 74 65 6e 64 65 64 20 62 79 20 61 64 64 69 6e xtended by addin
e210: 67 20 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e g new methods on
e220: 74 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20 to.** the end.
e230: 45 61 63 68 20 74 69 6d 65 20 73 75 63 68 20 61 Each time such a
e240: 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75 n extension occu
e250: 72 73 2c 20 74 68 65 20 69 56 65 72 73 69 6f 6e rs, the iVersion
e260: 20 66 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 field.** is inc
e270: 72 65 6d 65 6e 74 65 64 2e 20 20 54 68 65 20 69 remented. The i
e280: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 73 74 Version value st
e290: 61 72 74 65 64 20 6f 75 74 20 61 73 20 31 20 69 arted out as 1 i
e2a0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 n.** SQLite [ver
e2b0: 73 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b sion 3.5.0] on [
e2c0: 64 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 dateof:3.5.0], t
e2d0: 68 65 6e 20 69 6e 63 72 65 61 73 65 64 20 74 6f hen increased to
e2e0: 20 32 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69 74 2.** with SQLit
e2f0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30 e [version 3.7.0
e300: 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 ] on [dateof:3.7
e310: 2e 30 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e .0], and then in
e320: 63 72 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20 creased.** to 3
e330: 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72 with SQLite [ver
e340: 73 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b sion 3.7.6] on [
e350: 64 61 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 dateof:3.7.6].
e360: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 Additional field
e370: 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 70 70 65 s.** may be appe
e380: 6e 64 65 64 20 74 6f 20 74 68 65 20 73 71 6c 69 nded to the sqli
e390: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 61 te3_vfs object a
e3a0: 6e 64 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 nd the iVersion
e3b0: 76 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 value.** may inc
e3c0: 72 65 61 73 65 20 61 67 61 69 6e 20 69 6e 20 66 rease again in f
e3d0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
e3e0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 f SQLite..** Not
e3f0: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 e that the struc
e400: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 ture.** of the s
e410: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 qlite3_vfs objec
e420: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 t changes in the
e430: 20 74 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d transition from
e440: 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 .** SQLite [vers
e450: 69 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 ion 3.5.9] to [v
e460: 65 72 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e ersion 3.6.0] on
e470: 20 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a [dateof:3.6.0].
e480: 2a 2a 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 ** and yet the i
e490: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 Version field wa
e4a0: 73 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a s not modified..
e4b0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 **.** The szOsFi
e4c0: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 le field is the
e4d0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 size of the subc
e4e0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f lassed [sqlite3_
e4f0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 file].** structu
e500: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 re used by this
e510: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 VFS. mxPathname
e520: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 is the maximum
e530: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 length of.** a p
e540: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 athname in this
e550: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 VFS..**.** Regis
e560: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 tered sqlite3_vf
e570: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 s objects are ke
e580: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c pt on a linked l
e590: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a ist formed by.**
e5a0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 the pNext point
e5b0: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 er. The [sqlite
e5c0: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 3_vfs_register()
e5d0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
e5e0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 3_vfs_unregister
e5f0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d ()] interfaces m
e600: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a anage this list.
e610: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 ** in a thread-s
e620: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 afe way. The [s
e630: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 qlite3_vfs_find(
e640: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 )] interface.**
e650: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 searches the lis
e660: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 t. Neither the
e670: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 application code
e680: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 nor the VFS.**
e690: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 implementation s
e6a0: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e hould use the pN
e6b0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ext pointer..**.
e6c0: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 ** The pNext fie
e6d0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 ld is the only f
e6e0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 ield in the sqli
e6f0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 te3_vfs.** struc
e700: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 ture that SQLite
e710: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 will ever modif
e720: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 y. SQLite will
e730: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f only access.** o
e740: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 r modify this fi
e750: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e eld while holdin
e760: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 g a particular s
e770: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 tatic mutex..**
e780: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
e790: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 should never mod
e7a0: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 ify anything wit
e7b0: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f hin the sqlite3_
e7c0: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e vfs.** object on
e7d0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 ce the object ha
e7e0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 s been registere
e7f0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 d..**.** The zNa
e800: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 me field holds t
e810: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 he name of the V
e820: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 FS module. The
e830: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 name must.** be
e840: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c unique across al
e850: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a l VFS modules..*
e860: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 *.** [[sqlite3_v
e870: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 fs.xOpen]].** ^S
e880: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 QLite guarantees
e890: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e that the zFilen
e8a0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f ame parameter to
e8b0: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 xOpen.** is eit
e8c0: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 her a NULL point
e8d0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 er or string obt
e8e0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 ained.** from xF
e8f0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 ullPathname() wi
e900: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 th an optional s
e910: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 uffix added..**
e920: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 ^If a suffix is
e930: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 added to the zFi
e940: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
e950: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e , it will.** con
e960: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 sist of a single
e970: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 "-" character f
e980: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f ollowed by no mo
e990: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c re than.** 11 al
e9a0: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f phanumeric and/o
e9b0: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 r "-" characters
e9c0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 ..** ^SQLite fur
e9d0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 ther guarantees
e9e0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 that.** the stri
e9f0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 ng will be valid
ea00: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 and unchanged u
ea10: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 ntil xClose() is
ea20: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 .** called. Beca
ea30: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 use of the previ
ea40: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a ous sentence,.**
ea50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
ea60: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 le] can safely s
ea70: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 tore a pointer t
ea80: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d o the.** filenam
ea90: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f e if it needs to
eaa0: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 remember the fi
eab0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 lename for some
eac0: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 reason..** If th
ead0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 e zFilename para
eae0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 meter to xOpen i
eaf0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
eb00: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d then xOpen.** m
eb10: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f ust invent its o
eb20: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d wn temporary nam
eb30: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 e for the file.
eb40: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a ^Whenever the .
eb50: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 ** xFilename par
eb60: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 ameter is NULL i
eb70: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 t will also be t
eb80: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 he case that the
eb90: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 .** flags parame
eba0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 ter will include
ebb0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
ebc0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a LETEONCLOSE]..**
ebd0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 .** The flags ar
ebe0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 gument to xOpen(
ebf0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 ) includes all b
ec00: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 its set in.** th
ec10: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
ec20: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
ec30: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 n_v2()]. Or if
ec40: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
ec50: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
ec60: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 open16()] is use
ec70: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e d, then flags in
ec80: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a cludes at least.
ec90: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
eca0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 READWRITE] | [SQ
ecb0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
ecc0: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 ]. .** If xOpen(
ecd0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 ) opens a file r
ece0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 ead-only then it
ecf0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 sets *pOutFlags
ed00: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b to.** include [
ed10: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
ed20: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 ONLY]. Other bi
ed30: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 ts in *pOutFlags
ed40: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a may be set..**.
ed50: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c ** ^(SQLite will
ed60: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 also add one of
ed70: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 the following f
ed80: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 lags to the xOpe
ed90: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 n().** call, dep
eda0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 ending on the ob
edb0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 ject being opene
edc0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a d:.**.** <ul>.**
edd0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
ede0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 PEN_MAIN_DB].**
edf0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
ee00: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d EN_MAIN_JOURNAL]
ee10: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
ee20: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a E_OPEN_TEMP_DB].
ee30: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
ee40: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e _OPEN_TEMP_JOURN
ee50: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
ee60: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 LITE_OPEN_TRANSI
ee70: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 ENT_DB].** <li>
ee80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 [SQLITE_OPEN_SU
ee90: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 BJOURNAL].** <li
eea0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
eeb0: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a MASTER_JOURNAL].
eec0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
eed0: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f _OPEN_WAL].** </
eee0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ul>)^.**.** The
eef0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 file I/O impleme
ef00: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 ntation can use
ef10: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 the object type
ef20: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e flags to.** chan
ef30: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 ge the way it de
ef40: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 als with files.
ef50: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e For example, an
ef60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 application.**
ef70: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 that does not ca
ef80: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 re about crash r
ef90: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 ecovery or rollb
efa0: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a ack might make.*
efb0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 * the open of a
efc0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e journal file a n
efd0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f o-op. Writes to
efe0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f this journal wo
eff0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e uld.** also be n
f000: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 o-ops, and any a
f010: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 ttempt to read t
f020: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 he journal would
f030: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 return.** SQLIT
f040: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 E_IOERR. Or the
f050: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
f060: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 might recognize
f070: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a that a database.
f080: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 ** file will be
f090: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e doing page-align
f0a0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 ed sector reads
f0b0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 and writes in a
f0c0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 random.** order
f0d0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 and set up its I
f0e0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 /O subsystem acc
f0f0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ordingly..**.**
f100: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 SQLite might als
f110: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 o add one of the
f120: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 following flags
f130: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 to the xOpen me
f140: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e thod:.**.** <ul>
f150: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
f160: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
f170: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 OSE].** <li> [SQ
f180: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 LITE_OPEN_EXCLUS
f190: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a IVE].** </ul>.**
f1a0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
f1b0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
f1c0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 SE] flag means t
f1d0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 he file should b
f1e0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 e.** deleted whe
f1f0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 n it is closed.
f200: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 ^The [SQLITE_OP
f210: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
f220: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 ].** will be set
f230: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 for TEMP databa
f240: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f ses and their jo
f250: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e urnals, transien
f260: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 t.** databases,
f270: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e and subjournals.
f280: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c .**.** ^The [SQL
f290: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
f2a0: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 VE] flag is alwa
f2b0: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 ys used in conju
f2c0: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 nction.** with t
f2d0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
f2e0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 CREATE] flag, wh
f2f0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 ich are both dir
f300: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f ectly.** analogo
f310: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c us to the O_EXCL
f320: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 and O_CREAT fla
f330: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 gs of the POSIX
f340: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 open().** API.
f350: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f The SQLITE_OPEN_
f360: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 EXCLUSIVE flag,
f370: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 when paired with
f380: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f the .** SQLITE_
f390: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 OPEN_CREATE, is
f3a0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 used to indicate
f3b0: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c that file shoul
f3c0: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 d always.** be c
f3d0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 reated, and that
f3e0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 it is an error
f3f0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 if it already ex
f400: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c ists..** It is <
f410: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 i>not</i> used t
f420: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 o indicate the f
f430: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 ile should be op
f440: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 ened .** for exc
f450: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a lusive access..*
f460: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 *.** ^At least s
f470: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 zOsFile bytes of
f480: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f memory are allo
f490: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a cated by SQLite.
f4a0: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 ** to hold the
f4b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 [sqlite3_file] s
f4c0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 tructure passed
f4d0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 as the third.**
f4e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 argument to xOpe
f4f0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 n. The xOpen me
f500: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 thod does not ha
f510: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 ve to.** allocat
f520: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b e the structure;
f530: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 it should just
f540: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 fill it in. Not
f550: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f e that.** the xO
f560: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 pen method must
f570: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f set the sqlite3_
f580: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f file.pMethods to
f590: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c either.** a val
f5a0: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d id [sqlite3_io_m
f5b0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f ethods] object o
f5c0: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 r to NULL. xOpe
f5d0: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 n must do.** thi
f5e0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 s even if the op
f5f0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 en fails. SQLit
f600: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 e expects that t
f610: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e he sqlite3_file.
f620: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d pMethods.** elem
f630: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 ent will be vali
f640: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 d after xOpen re
f650: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 turns regardless
f660: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a of the success.
f670: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 ** or failure of
f680: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e the xOpen call.
f690: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 .**.** [[sqlite3
f6a0: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a _vfs.xAccess]].*
f6b0: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 * ^The flags arg
f6c0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 ument to xAccess
f6d0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 () may be [SQLIT
f6e0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d E_ACCESS_EXISTS]
f6f0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 .** to test for
f700: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 the existence of
f710: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c a file, or [SQL
f720: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
f730: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 RITE] to.** test
f740: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 whether a file
f750: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 is readable and
f760: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 writable, or [SQ
f770: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
f780: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 ].** to test whe
f790: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 ther a file is a
f7a0: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 t least readable
f7b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 . The SQLITE_AC
f7c0: 43 45 53 53 5f 52 45 41 44 0a 2a 2a 20 66 6c 61 CESS_READ.** fla
f7d0: 67 20 69 73 20 6e 65 76 65 72 20 61 63 74 75 61 g is never actua
f7e0: 6c 6c 79 20 75 73 65 64 20 61 6e 64 20 69 73 20 lly used and is
f7f0: 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 not implemented
f800: 69 6e 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a in the built-in.
f810: 2a 2a 20 56 46 53 65 73 20 6f 66 20 53 51 4c 69 ** VFSes of SQLi
f820: 74 65 2e 20 20 54 68 65 20 66 69 6c 65 20 69 73 te. The file is
f830: 20 6e 61 6d 65 64 20 62 79 20 74 68 65 20 73 65 named by the se
f840: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 61 6e cond argument an
f850: 64 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 d can be a.** di
f860: 72 65 63 74 6f 72 79 2e 20 54 68 65 20 78 41 63 rectory. The xAc
f870: 63 65 73 73 20 6d 65 74 68 6f 64 20 72 65 74 75 cess method retu
f880: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 rns [SQLITE_OK]
f890: 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 73 6f on success or so
f8a0: 6d 65 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 65 me.** non-zero e
f8b0: 72 72 6f 72 20 63 6f 64 65 20 69 66 20 74 68 65 rror code if the
f8c0: 72 65 20 69 73 20 61 6e 20 49 2f 4f 20 65 72 72 re is an I/O err
f8d0: 6f 72 20 6f 72 20 69 66 20 74 68 65 20 6e 61 6d or or if the nam
f8e0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 69 6c 65 e of.** the file
f8f0: 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 73 65 given in the se
f900: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
f910: 20 69 6c 6c 65 67 61 6c 2e 20 20 49 66 20 53 51 illegal. If SQ
f920: 4c 49 54 45 5f 4f 4b 0a 2a 2a 20 69 73 20 72 65 LITE_OK.** is re
f930: 74 75 72 6e 65 64 2c 20 74 68 65 6e 20 6e 6f 6e turned, then non
f940: 2d 7a 65 72 6f 20 6f 72 20 7a 65 72 6f 20 69 73 -zero or zero is
f950: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 written into *p
f960: 52 65 73 4f 75 74 20 74 6f 20 69 6e 64 69 63 61 ResOut to indica
f970: 74 65 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 te.** whether or
f980: 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 69 73 not the file is
f990: 20 61 63 63 65 73 73 69 62 6c 65 2e 20 20 0a 2a accessible. .*
f9a0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c *.** ^SQLite wil
f9b0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 l always allocat
f9c0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 e at least mxPat
f9d0: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f hname+1 bytes fo
f9e0: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 r the.** output
f9f0: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 buffer xFullPath
fa00: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 name. The exact
fa10: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 size of the out
fa20: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 put buffer.** is
fa30: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 also passed as
fa40: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 a parameter to b
fa50: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 oth methods. If
fa60: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 the output buff
fa70: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 er.** is not lar
fa80: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 ge enough, [SQLI
fa90: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f TE_CANTOPEN] sho
faa0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e uld be returned.
fab0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a Since this is.*
fac0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 * handled as a f
fad0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 atal error by SQ
fae0: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d Lite, vfs implem
faf0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 entations should
fb00: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 endeavor.** to
fb10: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 prevent this by
fb20: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 setting mxPathna
fb30: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 me to a sufficie
fb40: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 ntly large value
fb50: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e ..**.** The xRan
fb60: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 domness(), xSlee
fb70: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d p(), xCurrentTim
fb80: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e e(), and xCurren
fb90: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 tTimeInt64().**
fba0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e interfaces are n
fbb0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 ot strictly a pa
fbc0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 rt of the filesy
fbd0: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 stem, but they a
fbe0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 re.** included i
fbf0: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 n the VFS struct
fc00: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 ure for complete
fc10: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 ness..** The xRa
fc20: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 ndomness() funct
fc30: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ion attempts to
fc40: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 return nBytes by
fc50: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 tes.** of good-q
fc60: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 uality randomnes
fc70: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 s into zOut. Th
fc80: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 e return value i
fc90: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 s.** the actual
fca0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
fcb0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 of randomness ob
fcc0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 tained..** The x
fcd0: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 Sleep() method c
fce0: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e auses the callin
fcf0: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 g thread to slee
fd00: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 p for at.** leas
fd10: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
fd20: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 microseconds giv
fd30: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 en. ^The xCurre
fd40: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 ntTime().** meth
fd50: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c od returns a Jul
fd60: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 ian Day Number f
fd70: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 or the current d
fd80: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a ate and time as.
fd90: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f ** a floating po
fda0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 int value..** ^T
fdb0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 he xCurrentTimeI
fdc0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 nt64() method re
fdd0: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 turns, as an int
fde0: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e eger, the Julian
fdf0: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d .** Day Number m
fe00: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 ultiplied by 864
fe10: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 00000 (the numbe
fe20: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 r of millisecond
fe30: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f s in .** a 24-ho
fe40: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 ur day). .** ^S
fe50: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 QLite will use t
fe60: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 he xCurrentTimeI
fe70: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f nt64() method to
fe80: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 get the current
fe90: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d .** date and tim
fea0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 e if that method
feb0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 is available (i
fec0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 f iVersion is 2
fed0: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 or .** greater a
fee0: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 nd the function
fef0: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e pointer is not N
ff00: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 ULL) and will fa
ff10: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 ll back.** to xC
ff20: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 urrentTime() if
ff30: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 xCurrentTimeInt6
ff40: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 4() is unavailab
ff50: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 le..**.** ^The x
ff60: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c SetSystemCall(),
ff70: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 xGetSystemCall(
ff80: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 ), and xNestSyst
ff90: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 emCall() interfa
ffa0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 ces.** are not u
ffb0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 sed by the SQLit
ffc0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f e core. These o
ffd0: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 ptional interfac
ffe0: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a es are provided.
fff0: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 ** by some VFSes
10000 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 to facilitate t
10010 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 esting of the VF
10020 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 S code. By overr
10030 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d iding .** system
10040 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 calls with func
10050 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 tions under its
10060 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 control, a test
10070 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 program can.** s
10080 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 imulate faults a
10090 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 nd error conditi
100a0 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f ons that would o
100b0 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 therwise be diff
100c0 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f icult.** or impo
100d0 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 ssible to induce
100e0 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 . The set of sy
100f0 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 stem calls that
10100 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 can be overridde
10110 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d n.** varies from
10120 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 one VFS to anot
10130 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e her, and from on
10140 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 e version of the
10150 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 same VFS to the
10160 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 .** next. Appli
10170 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 cations that use
10180 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
10190 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 s must be prepar
101a0 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 ed for any.** or
101b0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e all of these in
101c0 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e terfaces to be N
101d0 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 ULL or for their
101e0 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 behavior to cha
101f0 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 nge.** from one
10200 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e release to the n
10210 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ext. Applicatio
10220 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 ns must not atte
10230 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a mpt to access.**
10240 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 any of these me
10250 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 thods if the iVe
10260 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 rsion of the VFS
10270 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e is less than 3.
10280 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
10290 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 ct sqlite3_vfs s
102a0 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 qlite3_vfs;.type
102b0 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 def void (*sqlit
102c0 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 e3_syscall_ptr)(
102d0 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 void);.struct sq
102e0 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e lite3_vfs {. in
102f0 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 t iVersion;
10300 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 /* Struct
10310 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 ure version numb
10320 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 er (currently 3)
10330 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 */. int szOsFi
10340 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f le; /
10350 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 * Size of subcla
10360 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c ssed sqlite3_fil
10370 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 e */. int mxPat
10380 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 hname;
10390 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 /* Maximum file
103a0 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 pathname length
103b0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 */. sqlite3_vfs
103c0 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a *pNext; /*
103d0 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 Next registered
103e0 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 VFS */. const
103f0 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 char *zName;
10400 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 /* Name of th
10410 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 is virtual file
10420 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 system */. void
10430 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 *pAppData;
10440 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 /* Pointer
10450 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 to application-s
10460 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a pecific data */.
10470 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 int (*xOpen)(s
10480 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
10490 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
104a0 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 sqlite3_file*,.
104b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e in
104c0 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f t flags, int *pO
104d0 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 utFlags);. int
104e0 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 (*xDelete)(sqlit
104f0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
10500 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 har *zName, int
10510 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 syncDir);. int
10520 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 (*xAccess)(sqlit
10530 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
10540 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 har *zName, int
10550 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 flags, int *pRes
10560 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 Out);. int (*xF
10570 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c ullPathname)(sql
10580 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
10590 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
105a0 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f t nOut, char *zO
105b0 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 ut);. void *(*x
105c0 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f DlOpen)(sqlite3_
105d0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
105e0 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 *zFilename);.
105f0 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 void (*xDlError)
10600 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
10610 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a nt nByte, char *
10620 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 zErrMsg);. void
10630 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c (*(*xDlSym)(sql
10640 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c ite3_vfs*,void*,
10650 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 const char *zSy
10660 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 mbol))(void);.
10670 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 void (*xDlClose)
10680 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 (sqlite3_vfs*, v
10690 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 oid*);. int (*x
106a0 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 Randomness)(sqli
106b0 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 te3_vfs*, int nB
106c0 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 yte, char *zOut)
106d0 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 ;. int (*xSleep
106e0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
106f0 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 int microseconds
10700 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 );. int (*xCurr
10710 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 entTime)(sqlite3
10720 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b _vfs*, double*);
10730 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 . int (*xGetLas
10740 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f tError)(sqlite3_
10750 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 vfs*, int, char
10760 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 *);. /*. ** Th
10770 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 e methods above
10780 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 are in version 1
10790 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 of the sqlite_v
107a0 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 fs object. ** d
107b0 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 efinition. Thos
107c0 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 e that follow ar
107d0 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 e added in versi
107e0 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 on 2 or later.
107f0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 */. int (*xCurr
10800 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 entTimeInt64)(sq
10810 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 lite3_vfs*, sqli
10820 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f te3_int64*);. /
10830 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f *. ** The metho
10840 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 ds above are in
10850 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 versions 1 and 2
10860 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 of the sqlite_v
10870 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 fs object.. **
10880 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 Those below are
10890 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e for version 3 an
108a0 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a d greater.. */.
108b0 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 int (*xSetSyst
108c0 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f emCall)(sqlite3_
108d0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
108e0 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 *zName, sqlite3
108f0 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 _syscall_ptr);.
10900 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c sqlite3_syscall
10910 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 _ptr (*xGetSyste
10920 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 mCall)(sqlite3_v
10930 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
10940 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 *zName);. const
10950 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 char *(*xNextSy
10960 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 stemCall)(sqlite
10970 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
10980 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a ar *zName);. /*
10990 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 . ** The method
109a0 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 s above are in v
109b0 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 ersions 1 throug
109c0 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 h 3 of the sqlit
109d0 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 e_vfs object..
109e0 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 ** New fields ma
109f0 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e y be appended in
10a00 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 future versions
10a10 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a . The iVersion.
10a20 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 ** value will
10a30 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 increment whenev
10a40 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e er this happens.
10a50 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a . */.};../*.**
10a60 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
10a70 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 for the xAccess
10a80 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a VFS method.**.*
10a90 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
10aa0 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 constants can be
10ab0 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 used as the thi
10ac0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a rd parameter to.
10ad0 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d ** the xAccess m
10ae0 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c ethod of an [sql
10af0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
10b00 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e . They determin
10b10 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f e.** what kind o
10b20 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 f permissions th
10b30 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
10b40 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e is looking for.
10b50 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f .** With SQLITE_
10b60 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 ACCESS_EXISTS, t
10b70 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
10b80 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 d.** simply chec
10b90 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
10ba0 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 ile exists..** W
10bb0 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
10bc0 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 S_READWRITE, the
10bd0 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
10be0 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ** checks whethe
10bf0 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 r the named dire
10c00 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 ctory is both re
10c10 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 adable and writa
10c20 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 ble.** (in other
10c30 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 words, if files
10c40 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 can be added, r
10c50 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 emoved, and rena
10c60 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 med within.** th
10c70 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a e directory)..**
10c80 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 The SQLITE_ACCE
10c90 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e SS_READWRITE con
10ca0 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 stant is current
10cb0 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 ly used only by
10cc0 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f the.** [temp_sto
10cd0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 re_directory pra
10ce0 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 gma], though thi
10cf0 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 s could change i
10d00 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 n a future.** re
10d10 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e lease of SQLite.
10d20 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f .** With SQLITE_
10d30 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 ACCESS_READ, the
10d40 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
10d50 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ** checks whethe
10d60 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 r the file is re
10d70 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c adable. The SQL
10d80 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 ITE_ACCESS_READ
10d90 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 constant is.** c
10da0 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c urrently unused,
10db0 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 though it might
10dc0 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 be used in a fu
10dd0 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a ture release of.
10de0 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 ** SQLite..*/.#d
10df0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 efine SQLITE_ACC
10e00 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a ESS_EXISTS 0.
10e10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
10e20 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 CCESS_READWRITE
10e30 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 1 /* Used by P
10e40 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 RAGMA temp_store
10e50 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 _directory */.#d
10e60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 efine SQLITE_ACC
10e70 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 ESS_READ 2
10e80 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a /* Unused */..
10e90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
10ea0 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 Flags for the xS
10eb0 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f hmLock VFS metho
10ec0 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e d.**.** These in
10ed0 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 teger constants
10ee0 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f define the vario
10ef0 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 us locking opera
10f00 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 tions.** allowed
10f10 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b by the xShmLock
10f20 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 method of [sqli
10f30 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e te3_io_methods].
10f40 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 The.** followi
10f50 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 ng are the only
10f60 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f legal combinatio
10f70 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 ns of flags to t
10f80 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d he.** xShmLock m
10f90 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c ethod:.**.** <ul
10fa0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 >.** <li> SQLIT
10fb0 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c E_SHM_LOCK | SQL
10fc0 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a ITE_SHM_SHARED.*
10fd0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 * <li> SQLITE_S
10fe0 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 HM_LOCK | SQLITE
10ff0 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a _SHM_EXCLUSIVE.*
11000 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 * <li> SQLITE_S
11010 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 HM_UNLOCK | SQLI
11020 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a TE_SHM_SHARED.**
11030 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 <li> SQLITE_SH
11040 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 M_UNLOCK | SQLIT
11050 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a E_SHM_EXCLUSIVE.
11060 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 ** </ul>.**.** W
11070 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 hen unlocking, t
11080 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f he same SHARED o
11090 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 r EXCLUSIVE flag
110a0 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 must be supplie
110b0 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 d as.** was give
110c0 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 n on the corresp
110d0 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a onding lock. .*
110e0 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 *.** The xShmLoc
110f0 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 k method can tra
11100 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 nsition between
11110 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 unlocked and SHA
11120 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 RED or.** betwee
11130 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 n unlocked and E
11140 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 XCLUSIVE. It ca
11150 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 nnot transition
11160 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a between SHARED.*
11170 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e * and EXCLUSIVE.
11180 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
11190 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 TE_SHM_UNLOCK
111a0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
111b0 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 LITE_SHM_LOCK
111c0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
111d0 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 SQLITE_SHM_SHARE
111e0 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e D 4.#defin
111f0 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 e SQLITE_SHM_EXC
11200 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a LUSIVE 8../*.
11210 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 ** CAPI3REF: Max
11220 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e imum xShmLock in
11230 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 dex.**.** The xS
11240 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e hmLock method on
11250 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
11260 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 hods] may use va
11270 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 lues.** between
11280 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 0 and this upper
11290 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f bound as its "o
112a0 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e ffset" argument.
112b0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
112c0 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 ore will never a
112d0 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 ttempt to acquir
112e0 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a e or release a.*
112f0 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f * lock outside o
11300 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a f this range.*/.
11310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
11320 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 HM_NLOCK
11330 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 8.../*.** CAPI3R
11340 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 EF: Initialize T
11350 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 he SQLite Librar
11360 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c y.**.** ^The sql
11370 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
11380 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 ) routine initia
11390 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c lizes the.** SQL
113a0 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 ite library. ^T
113b0 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 he sqlite3_shutd
113c0 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a own() routine.**
113d0 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 deallocates any
113e0 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 resources that
113f0 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 were allocated b
11400 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 y sqlite3_initia
11410 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 lize()..** These
11420 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 routines are de
11430 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e signed to aid in
11440 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c process initial
11450 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 ization and.** s
11460 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 hutdown on embed
11470 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f ded systems. Wo
11480 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 rkstation applic
11490 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 ations using.**
114a0 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 SQLite normally
114b0 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 do not need to i
114c0 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 nvoke either of
114d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
114e0 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 **.** A call to
114f0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
11500 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 ze() is an "effe
11510 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 ctive" call if i
11520 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 t is.** the firs
11530 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 t time sqlite3_i
11540 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 nitialize() is i
11550 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 nvoked during th
11560 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a e lifetime of.**
11570 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 the process, or
11580 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 if it is the fi
11590 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 rst time sqlite3
115a0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
115b0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c invoked.** foll
115c0 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 owing a call to
115d0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
115e0 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 (). ^(Only an e
115f0 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a ffective call.**
11600 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 of sqlite3_init
11610 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e ialize() does an
11620 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e y initialization
11630 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c . All other cal
11640 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 ls.** are harmle
11650 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a ss no-ops.)^.**.
11660 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c ** A call to sql
11670 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
11680 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 is an "effective
11690 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 " call if it is
116a0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c the first.** cal
116b0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
116c0 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 tdown() since th
116d0 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 e last sqlite3_i
116e0 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 nitialize(). ^(
116f0 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 Only.** an effec
11700 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c tive call to sql
11710 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
11720 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 does any deiniti
11730 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c alization..** Al
11740 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 l other valid ca
11750 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 lls to sqlite3_s
11760 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 hutdown() are ha
11770 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e rmless no-ops.)^
11780 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
11790 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
117a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 interface is thr
117b0 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c eadsafe, but sql
117c0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a ite3_shutdown().
117d0 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 ** is not. The
117e0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
117f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 () interface mus
11800 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 t only be called
11810 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c from a.** singl
11820 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f e thread. All o
11830 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f pen [database co
11840 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 nnections] must
11850 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c be closed and al
11860 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 l.** other SQLit
11870 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 e resources must
11880 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
11890 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e prior to invokin
118a0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 g.** sqlite3_shu
118b0 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 tdown()..**.** A
118c0 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 mong other thing
118d0 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 s, ^sqlite3_init
118e0 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e ialize() will in
118f0 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
11900 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 os_init(). Simi
11910 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f larly, ^sqlite3_
11920 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 shutdown().** wi
11930 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ll invoke sqlite
11940 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 3_os_end()..**.*
11950 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
11960 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
11970 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ine returns [SQL
11980 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
11990 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 ss..** ^If for s
119a0 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 ome reason, sqli
119b0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
119c0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e is unable to in
119d0 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 itialize.** the
119e0 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 library (perhaps
119f0 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f it is unable to
11a00 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 allocate a need
11a10 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 ed resource such
11a20 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 .** as a mutex)
11a30 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 it returns an [e
11a40 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 rror code] other
11a50 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b than [SQLITE_OK
11a60 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ]..**.** ^The sq
11a70 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
11a80 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 () routine is ca
11a90 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 lled internally
11aa0 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a by many other.**
11ab0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
11ac0 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 es so that an ap
11ad0 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c plication usuall
11ae0 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 y does not need
11af0 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c to.** invoke sql
11b00 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
11b10 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 ) directly. For
11b20 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 example, [sqlit
11b30 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 e3_open()].** ca
11b40 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 lls sqlite3_init
11b50 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 ialize() so the
11b60 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 SQLite library w
11b70 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 ill be automatic
11b80 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 ally.** initiali
11b90 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 zed when [sqlite
11ba0 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 3_open()] is cal
11bb0 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f led if it has no
11bc0 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 t be initialized
11bd0 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 .** already. ^H
11be0 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 owever, if SQLit
11bf0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
11c00 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f th the [SQLITE_O
11c10 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a MIT_AUTOINIT].**
11c20 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
11c30 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 tion, then the a
11c40 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 utomatic calls t
11c50 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 o sqlite3_initia
11c60 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d lize().** are om
11c70 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 itted and the ap
11c80 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 plication must c
11c90 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 all sqlite3_init
11ca0 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c ialize() directl
11cb0 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 y.** prior to us
11cc0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 ing any other SQ
11cd0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 Lite interface.
11ce0 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 For maximum por
11cf0 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 tability,.** it
11d00 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 is recommended t
11d10 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 hat applications
11d20 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 always invoke s
11d30 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
11d40 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 e().** directly
11d50 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 prior to using a
11d60 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ny other SQLite
11d70 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 interface. Futu
11d80 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f re releases.** o
11d90 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 f SQLite may req
11da0 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f uire this. In o
11db0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
11dc0 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 behavior exhibit
11dd0 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 ed.** when SQLit
11de0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
11df0 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f th [SQLITE_OMIT_
11e00 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 AUTOINIT] might
11e10 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 become the.** de
11e20 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 fault behavior i
11e30 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 n some future re
11e40 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e lease of SQLite.
11e50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
11e60 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 e3_os_init() rou
11e70 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 tine does operat
11e80 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 ing-system speci
11e90 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a fic.** initializ
11ea0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c ation of the SQL
11eb0 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 ite library. Th
11ec0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 e sqlite3_os_end
11ed0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e ().** routine un
11ee0 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 does the effect
11ef0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e of sqlite3_os_in
11f00 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 it(). Typical t
11f10 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 asks.** performe
11f20 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 d by these routi
11f30 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f nes include allo
11f40 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f cation or deallo
11f50 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 cation.** of sta
11f60 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 tic resources, i
11f70 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 nitialization of
11f80 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 global variable
11f90 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 s,.** setting up
11fa0 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 a default [sqli
11fb0 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c te3_vfs] module,
11fc0 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a or setting up.*
11fd0 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 * a default conf
11fe0 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 iguration using
11ff0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
12000 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 )]..**.** The ap
12010 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
12020 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 never invoke ei
12030 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f ther sqlite3_os_
12040 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c init().** or sql
12050 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 ite3_os_end() di
12060 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 rectly. The app
12070 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
12080 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 only invoke.** s
12090 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
120a0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f e() and sqlite3_
120b0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 shutdown(). The
120c0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
120d0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
120e0 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 is called automa
120f0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 tically by sqlit
12100 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
12110 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f and.** sqlite3_o
12120 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 s_end() is calle
12130 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 d by sqlite3_shu
12140 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 tdown(). Approp
12150 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 riate.** impleme
12160 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c ntations for sql
12170 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 ite3_os_init() a
12180 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nd sqlite3_os_en
12190 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 d().** are built
121a0 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 into SQLite whe
121b0 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 n it is compiled
121c0 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f for Unix, Windo
121d0 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 ws, or OS/2..**
121e0 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 When [custom bui
121f0 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 lds | built for
12200 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d other platforms]
12210 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b .** (using the [
12220 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d SQLITE_OS_OTHER=
12230 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 1] compile-time.
12240 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 ** option) the a
12250 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
12260 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c supply a suitabl
12270 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
12280 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
12290 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 os_init() and sq
122a0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 lite3_os_end().
122b0 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d An application-
122c0 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c supplied.** impl
122d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 ementation of sq
122e0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
122f0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e or sqlite3_os_en
12300 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 d().** must retu
12310 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f rn [SQLITE_OK] o
12320 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f n success and so
12330 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 me other [error
12340 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 code] upon.** fa
12350 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ilure..*/.int sq
12360 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
12370 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 (void);.int sqli
12380 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 te3_shutdown(voi
12390 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f d);.int sqlite3_
123a0 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 os_init(void);.i
123b0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nt sqlite3_os_en
123c0 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 d(void);../*.**
123d0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
123e0 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 uring The SQLite
123f0 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 Library.**.** T
12400 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 he sqlite3_confi
12410 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 g() interface is
12420 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c used to make gl
12430 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 obal configurati
12440 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f on.** changes to
12450 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 SQLite in order
12460 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 to tune SQLite
12470 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 to the specific
12480 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 needs of.** the
12490 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 application. Th
124a0 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 e default config
124b0 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d uration is recom
124c0 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a mended for most.
124d0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** applications
124e0 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 and so this rout
124f0 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e ine is usually n
12500 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 ot necessary. I
12510 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 t is.** provided
12520 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 to support rare
12530 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 applications wi
12540 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 th unusual needs
12550 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 ..**.** <b>The s
12560 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
12570 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 interface is not
12580 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65 threadsafe. The
12590 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 application.**
125a0 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 must ensure that
125b0 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 no other SQLite
125c0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
125d0 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 invoked by other
125e0 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c .** threads whil
125f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
12600 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f () is running.</
12610 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c b>.**.** The sql
12620 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e ite3_config() in
12630 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f terface.** may o
12640 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 nly be invoked p
12650 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 rior to library
12660 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 initialization u
12670 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
12680 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f _initialize()] o
12690 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e r after shutdown
126a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 by [sqlite3_shu
126b0 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 tdown()]..** ^If
126c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
126d0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 ) is called afte
126e0 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 r [sqlite3_initi
126f0 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 alize()] and bef
12700 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ore.** [sqlite3_
12710 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e shutdown()] then
12720 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 it will return
12730 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a SQLITE_MISUSE..*
12740 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c * Note, however,
12750 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 that ^sqlite3_c
12760 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 onfig() can be c
12770 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 alled as part of
12780 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e the.** implemen
12790 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 tation of an app
127a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
127b0 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 [sqlite3_os_ini
127c0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 t()]..**.** The
127d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
127e0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 o sqlite3_config
127f0 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 () is an integer
12800 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 .** [configurati
12810 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 on option] that
12820 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 determines.** wh
12830 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 at property of S
12840 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 QLite is to be c
12850 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 onfigured. Subs
12860 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 equent arguments
12870 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 .** vary dependi
12880 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 ng on the [confi
12890 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d guration option]
128a0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 .** in the first
128b0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
128c0 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 ^When a configu
128d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
128e0 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f set, sqlite3_co
128f0 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b nfig() returns [
12900 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e SQLITE_OK]..** ^
12910 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 If the option is
12920 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 unknown or SQLi
12930 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 te is unable to
12940 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a set the option.*
12950 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 * then this rout
12960 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f ine returns a no
12970 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f n-zero [error co
12980 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 de]..*/.int sqli
12990 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 te3_config(int,
129a0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ...);../*.** CAP
129b0 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 I3REF: Configure
129c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
129d0 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a tions.** METHOD:
129e0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 sqlite3.**.** T
129f0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f he sqlite3_db_co
12a00 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
12a10 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 is used to make
12a20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a configuration.*
12a30 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b * changes to a [
12a40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
12a50 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 ion]. The inter
12a60 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 face is similar
12a70 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
12a80 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 onfig()] except
12a90 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 that the changes
12aa0 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 apply to a sing
12ab0 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 le.** [database
12ac0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 connection] (spe
12ad0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 cified in the fi
12ae0 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a rst argument)..*
12af0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 *.** The second
12b00 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
12b10 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c te3_db_config(D,
12b20 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a V,...) is the.*
12b30 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 * [SQLITE_DBCONF
12b40 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 IG_LOOKASIDE | c
12b50 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 onfiguration ver
12b60 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 b] - an integer
12b70 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e code .** that in
12b80 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 dicates what asp
12b90 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 ect of the [data
12ba0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
12bb0 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 is being config
12bc0 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 ured..** Subsequ
12bd0 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 ent arguments va
12be0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 ry depending on
12bf0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f the configuratio
12c00 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 n verb..**.** ^C
12c10 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
12c20 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 db_config() retu
12c30 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 rn SQLITE_OK if
12c40 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 and only if.** t
12c50 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 he call is consi
12c60 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c dered successful
12c70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
12c80 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 _db_config(sqlit
12c90 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e e3*, int op, ...
12ca0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
12cb0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 EF: Memory Alloc
12cc0 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a ation Routines.*
12cd0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
12ce0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
12cf0 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 defines the inte
12d00 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 rface between SQ
12d10 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d Lite.** and low-
12d20 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c level memory all
12d30 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
12d40 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a ..**.** This obj
12d50 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f ect is used in o
12d60 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e nly one place in
12d70 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 the SQLite inte
12d80 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e rface..** A poin
12d90 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
12da0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
12db0 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e t is the argumen
12dc0 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 t to.** [sqlite3
12dd0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 _config()] when
12de0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f the configuratio
12df0 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b n option is.** [
12e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
12e10 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 LLOC] or [SQLITE
12e20 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f _CONFIG_GETMALLO
12e30 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 C]. .** By crea
12e40 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 ting an instance
12e50 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a of this object.
12e60 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 ** and passing i
12e70 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f t to [sqlite3_co
12e80 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f nfig]([SQLITE_CO
12e90 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a NFIG_MALLOC]).**
12ea0 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 during configur
12eb0 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 ation, an applic
12ec0 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 ation can specif
12ed0 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 y an alternative
12ee0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
12ef0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 ation subsystem
12f00 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 for SQLite to us
12f10 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 e for all of its
12f20 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f .** dynamic memo
12f30 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 ry needs..**.**
12f40 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 Note that SQLite
12f50 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 comes with seve
12f60 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 ral [built-in me
12f70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d mory allocators]
12f80 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 .** that are per
12f90 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 fectly adequate
12fa0 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c for the overwhel
12fb0 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 ming majority of
12fc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a applications.**
12fd0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f and that this o
12fe0 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 bject is only us
12ff0 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d eful to a tiny m
13000 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 inority of appli
13010 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 cations.** with
13020 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f specialized memo
13030 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 ry allocation re
13040 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 quirements. Thi
13050 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 s object is.** a
13060 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 lso used during
13070 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 testing of SQLit
13080 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 e in order to sp
13090 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 ecify an alterna
130a0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 tive.** memory a
130b0 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 llocator that si
130c0 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f mulates memory o
130d0 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e ut-of-memory con
130e0 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 ditions in.** or
130f0 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 der to verify th
13100 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 at SQLite recove
13110 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 rs gracefully fr
13120 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 om such.** condi
13130 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tions..**.** The
13140 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c xMalloc, xReall
13150 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 oc, and xFree me
13160 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 thods must work
13170 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c like the.** mall
13180 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 oc(), realloc()
13190 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 and free() funct
131a0 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 ions from the st
131b0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
131c0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 ..** ^SQLite gua
131d0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 rantees that the
131e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
131f0 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 to.** xRealloc
13200 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 is always a valu
13210 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 e returned by a
13220 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 prior call to xR
13230 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 oundup..**.** xS
13240 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 ize should retur
13250 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 n the allocated
13260 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 size of a memory
13270 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 allocation.** p
13280 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e reviously obtain
13290 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 ed from xMalloc
132a0 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 or xRealloc. Th
132b0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
132c0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 .** is always at
132d0 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 least as big as
132e0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 the requested s
132f0 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c ize but may be l
13300 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 arger..**.** The
13310 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 xRoundup method
13320 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f returns what wo
13330 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 uld be the alloc
13340 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 ated size of.**
13350 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
13360 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 ion given a part
13370 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 icular requested
13380 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d size. Most mem
13390 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 ory.** allocator
133a0 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 s round up memor
133b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 y allocations at
133c0 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 least to the ne
133d0 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f xt multiple.** o
133e0 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 f 8. Some alloc
133f0 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 ators round up t
13400 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 o a larger multi
13410 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 ple or to a powe
13420 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 r of 2..** Every
13430 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
13440 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e on request comin
13450 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 g in through [sq
13460 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a lite3_malloc()].
13470 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 ** or [sqlite3_r
13480 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 ealloc()] first
13490 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 calls xRoundup.
134a0 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 If xRoundup ret
134b0 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 urns 0, .** that
134c0 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 causes the corr
134d0 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 esponding memory
134e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 allocation to f
134f0 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ail..**.** The x
13500 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 Init method init
13510 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f ializes the memo
13520 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 ry allocator. F
13530 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 or example,.** i
13540 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 t might allocate
13550 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 any require mut
13560 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 exes or initiali
13570 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 ze internal data
13580 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 .** structures.
13590 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d The xShutdown m
135a0 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 ethod is invoked
135b0 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 (indirectly) by
135c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 .** [sqlite3_shu
135d0 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f tdown()] and sho
135e0 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 uld deallocate a
135f0 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 ny resources acq
13600 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 uired.** by xIni
13610 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 t. The pAppData
13620 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 pointer is used
13630 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 as the only par
13640 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e ameter to.** xIn
13650 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e it and xShutdown
13660 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 ..**.** SQLite h
13670 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 olds the [SQLITE
13680 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 _MUTEX_STATIC_MA
13690 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e STER] mutex when
136a0 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 it invokes.** t
136b0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c he xInit method,
136c0 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 so the xInit me
136d0 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 thod need not be
136e0 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 threadsafe. Th
136f0 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d e.** xShutdown m
13700 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 ethod is only ca
13710 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 lled from [sqlit
13720 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 e3_shutdown()] s
13730 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 o it does.** not
13740 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 need to be thre
13750 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 adsafe either.
13760 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 For all other me
13770 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a thods, SQLite.**
13780 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 holds the [SQLI
13790 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
137a0 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f MEM] mutex as lo
137b0 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 ng as the.** [SQ
137c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
137d0 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 TATUS] configura
137e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 tion option is t
137f0 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a urned on (which.
13800 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 ** it is by defa
13810 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 ult) and so the
13820 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f methods are auto
13830 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c matically serial
13840 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 ized..** However
13850 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e , if [SQLITE_CON
13860 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 FIG_MEMSTATUS] i
13870 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e s disabled, then
13880 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 the other.** me
13890 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 thods must be th
138a0 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 readsafe or else
138b0 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 make their own
138c0 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 arrangements for
138d0 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f .** serializatio
138e0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 n..**.** SQLite
138f0 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b will never invok
13900 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 e xInit() more t
13910 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 han once without
13920 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a an intervening.
13930 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 ** call to xShut
13940 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 down()..*/.typed
13950 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
13960 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 3_mem_methods sq
13970 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
13980 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 s;.struct sqlite
13990 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 3_mem_methods {.
139a0 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f void *(*xMallo
139b0 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 c)(int);
139c0 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 /* Memory alloc
139d0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a ation function *
139e0 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 /. void (*xFree
139f0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 )(void*);
13a00 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 /* Free a pri
13a10 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f or allocation */
13a20 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c . void *(*xReal
13a30 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b loc)(void*,int);
13a40 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 /* Resize an a
13a50 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 llocation */. i
13a60 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 nt (*xSize)(void
13a70 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a *); /*
13a80 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 Return the size
13a90 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f of an allocatio
13aa0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f n */. int (*xRo
13ab0 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 undup)(int);
13ac0 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 /* Round u
13ad0 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 p request size t
13ae0 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a o allocation siz
13af0 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e e */. int (*xIn
13b00 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 it)(void*);
13b10 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c /* Initial
13b20 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 ize the memory a
13b30 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f llocator */. vo
13b40 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 id (*xShutdown)(
13b50 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 void*); /*
13b60 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 Deinitialize the
13b70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
13b80 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 r */. void *pAp
13b90 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 pData;
13ba0 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e /* Argumen
13bb0 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 t to xInit() and
13bc0 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a xShutdown() */.
13bd0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
13be0 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f EF: Configuratio
13bf0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 n Options.** KEY
13c00 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 WORDS: {configur
13c10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a ation option}.**
13c20 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
13c30 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 nts are the avai
13c40 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f lable integer co
13c50 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
13c60 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 ons that.** can
13c70 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
13c80 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
13c90 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
13ca0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
13cb0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 ace..**.** New c
13cc0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
13cd0 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 ions may be adde
13ce0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
13cf0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
13d00 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 ** Existing conf
13d10 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
13d20 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f s might be disco
13d30 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 ntinued. Applic
13d40 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
13d50 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 check the retur
13d60 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c n code from [sql
13d70 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 ite3_config()] t
13d80 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
13d90 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 .** the call wor
13da0 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ked. The [sqlit
13db0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 e3_config()] int
13dc0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
13dd0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f rn a.** non-zero
13de0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
13df0 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 a discontinued
13e00 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 or unsupported c
13e10 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
13e20 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 ion.** is invoke
13e30 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a d..**.** <dl>.**
13e40 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
13e50 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 _SINGLETHREAD]]
13e60 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
13e70 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f G_SINGLETHREAD</
13e80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 dt>.** <dd>There
13e90 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 are no argument
13ea0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
13eb0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 . ^This option
13ec0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 sets the.** [thr
13ed0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 eading mode] to
13ee0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 Single-thread.
13ef0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
13f00 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 it disables.** a
13f10 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 ll mutexing and
13f20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f puts SQLite into
13f30 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 a mode where it
13f40 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 can only be use
13f50 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 d.** by a single
13f60 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 thread. ^If S
13f70 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
13f80 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 d with.** the [S
13f90 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
13fa0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 | SQLITE_THREAD
13fb0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d SAFE=0] compile-
13fc0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e time option then
13fd0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f .** it is not po
13fe0 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 ssible to change
13ff0 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 the [threading
14000 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 mode] from its d
14010 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 efault.** value
14020 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 of Single-thread
14030 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 and so [sqlite3
14040 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 _config()] will
14050 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 return .** [SQLI
14060 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c TE_ERROR] if cal
14070 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c led with the SQL
14080 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
14090 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 ETHREAD.** confi
140a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e guration option.
140b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
140c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
140d0 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 ITHREAD]] <dt>SQ
140e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
140f0 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 ITHREAD</dt>.**
14100 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f <dd>There are no
14110 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
14120 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 is option. ^Thi
14130 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 s option sets th
14140 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 e.** [threading
14150 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 mode] to Multi-t
14160 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 hread. In other
14170 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 words, it disab
14180 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 les.** mutexing
14190 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
141a0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 nection] and [pr
141b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
141c0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 ] objects..** Th
141d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 e application is
141e0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
141f0 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 serializing acc
14200 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 ess to.** [datab
14210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
14220 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
14230 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 tatements]. But
14240 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a other mutexes.*
14250 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f * are enabled so
14260 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
14270 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 l be safe to use
14280 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 in a multi-thre
14290 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d aded.** environm
142a0 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e ent as long as n
142b0 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 o two threads at
142c0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 tempt to use the
142d0 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 same.** [databa
142e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
142f0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e t the same time.
14300 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 ^If SQLite is
14310 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
14320 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
14330 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
14340 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
14350 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
14360 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 on then.** it is
14370 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f not possible to
14380 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 set the Multi-t
14390 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 hread [threading
143a0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 mode] and.** [s
143b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
143c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
143d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 LITE_ERROR] if c
143e0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a alled with the.*
143f0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f * SQLITE_CONFIG_
14400 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 MULTITHREAD conf
14410 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
14420 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
14430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 QLITE_CONFIG_SER
14440 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 IALIZED]] <dt>SQ
14450 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
14460 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c ALIZED</dt>.** <
14470 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 dd>There are no
14480 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 arguments to thi
14490 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 s option. ^This
144a0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 option sets the
144b0 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d .** [threading m
144c0 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a ode] to Serializ
144d0 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 ed. In other wor
144e0 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 ds, this option
144f0 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d enables.** all m
14500 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 utexes including
14510 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a the recursive.*
14520 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 * mutexes on [da
14530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
14540 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 n] and [prepared
14550 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 statement] obje
14560 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 cts..** In this
14570 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 mode (which is t
14580 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 he default when
14590 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
145a0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 ed with.** [SQLI
145b0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d TE_THREADSAFE=1]
145c0 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 ) the SQLite lib
145d0 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 rary will itself
145e0 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 serialize acces
145f0 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 s.** to [databas
14600 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 e connections] a
14610 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 nd [prepared sta
14620 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 tements] so that
14630 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 the.** applicat
14640 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 ion is free to u
14650 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 se the same [dat
14660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
14670 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 ] or the.** same
14680 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
14690 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 ment] in differe
146a0 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 nt threads at th
146b0 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 e same time..**
146c0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
146d0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
146e0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
146f0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
14700 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
14710 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
14720 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e then.** it is n
14730 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 ot possible to s
14740 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 et the Serialize
14750 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 d [threading mod
14760 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 e] and.** [sqlit
14770 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c e3_config()] wil
14780 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
14790 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 _ERROR] if calle
147a0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 d with the.** SQ
147b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
147c0 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 ALIZED configura
147d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 tion option.</dd
147e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
147f0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d _CONFIG_MALLOC]]
14800 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
14810 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a IG_MALLOC</dt>.*
14820 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c * <dd> ^(The SQL
14830 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
14840 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 C option takes a
14850 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
14860 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 which is .** a
14870 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
14880 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
14890 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
148a0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a ds] structure..*
148b0 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 * The argument s
148c0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 pecifies.** alte
148d0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 rnative low-leve
148e0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
148f0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 ion routines to
14900 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 be used in place
14910 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 of.** the memor
14920 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 y allocation rou
14930 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f tines built into
14940 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 SQLite.)^ ^SQLi
14950 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 te makes.** its
14960 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 own private copy
14970 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 of the content
14980 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
14990 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 mem_methods] str
149a0 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 ucture.** before
149b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
149c0 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 nfig()] call ret
149d0 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a urns.</dd>.**.**
149e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
149f0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 _GETMALLOC]] <dt
14a00 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
14a10 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a ETMALLOC</dt>.**
14a20 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 <dd> ^(The SQLI
14a30 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
14a40 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 LOC option takes
14a50 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
14a60 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 nt which.** is a
14a70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
14a80 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
14a90 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
14aa0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a ods] structure..
14ab0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
14ac0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 mem_methods].**
14ad0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c structure is fil
14ae0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 led with the cur
14af0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d rently defined m
14b00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
14b10 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 routines.)^.**
14b20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 This option can
14b30 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c be used to overl
14b40 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 oad the default
14b50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
14b60 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 n.** routines wi
14b70 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 th a wrapper tha
14b80 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 t simulations me
14b90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
14ba0 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 failure or.** tr
14bb0 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 acks memory usag
14bc0 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 e, for example.
14bd0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
14be0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c LITE_CONFIG_SMAL
14bf0 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 L_MALLOC]] <dt>S
14c00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 QLITE_CONFIG_SMA
14c10 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a LL_MALLOC</dt>.*
14c20 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 * <dd> ^The SQLI
14c30 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f TE_CONFIG_SMALL_
14c40 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 MALLOC option ta
14c50 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d kes single argum
14c60 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65 20 69 ent of.** type i
14c70 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 nt, interpreted
14c80 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 as a boolean, wh
14c90 69 63 68 20 69 66 20 74 72 75 65 20 70 72 6f 76 ich if true prov
14ca0 69 64 65 73 20 61 20 68 69 6e 74 20 74 6f 0a 2a ides a hint to.*
14cb0 2a 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 * SQLite that it
14cc0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 6c 61 should avoid la
14cd0 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 rge memory alloc
14ce0 61 74 69 6f 6e 73 20 69 66 20 70 6f 73 73 69 62 ations if possib
14cf0 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 le..** SQLite wi
14d00 6c 6c 20 72 75 6e 20 66 61 73 74 65 72 20 69 66 ll run faster if
14d10 20 69 74 20 69 73 20 66 72 65 65 20 74 6f 20 6d it is free to m
14d20 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 ake large memory
14d30 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a 2a allocations,.**
14d40 20 62 75 74 20 73 6f 6d 65 20 61 70 70 6c 69 63 but some applic
14d50 61 74 69 6f 6e 20 6d 69 67 68 74 20 70 72 65 66 ation might pref
14d60 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77 65 72 er to run slower
14d70 20 69 6e 20 65 78 63 68 61 6e 67 65 20 66 6f 72 in exchange for
14d80 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 61 .** guarantees a
14d90 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72 61 67 bout memory frag
14da0 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 61 mentation that a
14db0 72 65 20 70 6f 73 73 69 62 6c 65 20 69 66 20 6c re possible if l
14dc0 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 arge.** allocati
14dd0 6f 6e 73 20 61 72 65 20 61 76 6f 69 64 65 64 2e ons are avoided.
14de0 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e This hint is n
14df0 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a 20 ormally off..**
14e00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
14e10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
14e20 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 TATUS]] <dt>SQLI
14e30 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
14e40 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TUS</dt>.** <dd>
14e50 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^The SQLITE_CON
14e60 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 FIG_MEMSTATUS op
14e70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c tion takes singl
14e80 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 e argument of ty
14e90 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 pe int,.** inter
14ea0 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c preted as a bool
14eb0 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c ean, which enabl
14ec0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 es or disables t
14ed0 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 he collection of
14ee0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
14ef0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 ation statistics
14f00 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 . ^(When memory
14f10 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 allocation stati
14f20 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 stics are.** dis
14f30 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f abled, the follo
14f40 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 wing SQLite inte
14f50 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f rfaces become no
14f60 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a n-operational:.*
14f70 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c * <ul>.** <l
14f80 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f i> [sqlite3_memo
14f90 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 ry_used()].**
14fa0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 <li> [sqlite3_me
14fb0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
14fc0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
14fd0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c ite3_soft_heap_l
14fe0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c imit64()].** <
14ff0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 li> [sqlite3_sta
15000 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f tus64()].** </
15010 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 ul>)^.** ^Memory
15020 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
15030 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c istics are enabl
15040 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e ed by default un
15050 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a less SQLite is.*
15060 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 * compiled with
15070 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f [SQLITE_DEFAULT_
15080 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 MEMSTATUS]=0 in
15090 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 which case memor
150a0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 y.** allocation
150b0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 statistics are d
150c0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
150d0 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a lt..** </dd>.**.
150e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
150f0 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 IG_SCRATCH]] <dt
15100 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
15110 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c CRATCH</dt>.** <
15120 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 dd> The SQLITE_C
15130 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 ONFIG_SCRATCH op
15140 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 tion is no longe
15150 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64 3e r used..** </dd>
15160 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
15170 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
15180 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
15190 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f NFIG_PAGECACHE</
151a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 dt>.** <dd> ^The
151b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
151c0 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 AGECACHE option
151d0 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f specifies a memo
151e0 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 ry pool.** that
151f0 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 SQLite can use f
15200 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 or the database
15210 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 page cache with
15220 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 the default page
15230 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d .** cache implem
15240 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 entation. .** T
15250 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f his configuratio
15260 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f n option is a no
15270 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63 -op if an applic
15280 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 ation-define pag
15290 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 e.** cache imple
152a0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 mentation is loa
152b0 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 ded using the [S
152c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
152d0 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 CHE2]..** ^There
152e0 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d are three argum
152f0 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 ents to SQLITE_C
15300 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a ONFIG_PAGECACHE:
15310 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a A pointer to.**
15320 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 8-byte aligned
15330 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 memory (pMem), t
15340 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 he size of each
15350 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 page cache line
15360 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 (sz),.** and the
15370 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65 number of cache
15380 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 lines (N)..** T
15390 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 he sz argument s
153a0 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a hould be the siz
153b0 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 e of the largest
153c0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a database page.*
153d0 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 * (a power of tw
153e0 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e o between 512 an
153f0 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f d 65536) plus so
15400 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20 66 me extra bytes f
15410 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 or each.** page
15420 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 header. ^The nu
15430 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 mber of extra by
15440 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 tes needed by th
15450 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a e page header.**
15460 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e can be determin
15470 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 ed using [SQLITE
15480 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 _CONFIG_PCACHE_H
15490 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 DRSZ]..** ^It is
154a0 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 harmless, apart
154b0 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 from the wasted
154c0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 memory,.** for
154d0 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 the sz parameter
154e0 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 to be larger th
154f0 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 an necessary. T
15500 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d he pMem.** argum
15510 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 ent must be eith
15520 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 er a NULL pointe
15530 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 r or a pointer t
15540 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 o an 8-byte.** a
15550 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 ligned block of
15560 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 memory of at lea
15570 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f st sz*N bytes, o
15580 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 therwise.** subs
15590 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 equent behavior
155a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
155b0 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e ^When pMem is n
155c0 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 ot NULL, SQLite
155d0 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75 will strive to u
155e0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 se the memory pr
155f0 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 ovided.** to sat
15600 69 73 66 79 20 70 61 67 65 20 63 61 63 68 65 20 isfy page cache
15610 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 needs, falling b
15620 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ack to [sqlite3_
15630 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 malloc()] if.**
15640 61 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e a page cache lin
15650 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e e is larger than
15660 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20 sz bytes or if
15670 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 all of the pMem
15680 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 buffer.** is exh
15690 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 austed..** ^If p
156a0 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 Mem is NULL and
156b0 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 N is non-zero, t
156c0 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 61 73 hen each databas
156d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
156e0 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 does an initial
156f0 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 bulk allocation
15700 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d for page cache m
15710 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 emory.** from [s
15720 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
15730 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20 sufficient for
15740 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66 N cache lines if
15750 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f N is positive o
15760 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 r.** of -1024*N
15770 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65 bytes if N is ne
15780 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 gative, . ^If ad
15790 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 ditional.** page
157a0 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 cache memory is
157b0 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 needed beyond w
157c0 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 hat is provided
157d0 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a by the initial.*
157e0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 * allocation, th
157f0 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 en SQLite goes t
15800 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f o [sqlite3_mallo
15810 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20 c()] separately
15820 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 for each.** addi
15830 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e tional cache lin
15840 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b e. </dd>.**.** [
15850 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 [SQLITE_CONFIG_H
15860 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 EAP]] <dt>SQLITE
15870 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 _CONFIG_HEAP</dt
15880 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 >.** <dd> ^The S
15890 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
158a0 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 P option specifi
158b0 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f es a static memo
158c0 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 ry buffer .** th
158d0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 at SQLite will u
158e0 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 se for all of it
158f0 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 s dynamic memory
15900 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 allocation need
15910 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 s.** beyond thos
15920 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 e provided for b
15930 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 y [SQLITE_CONFIG
15940 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 _PAGECACHE]..**
15950 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
15960 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 IG_HEAP option i
15970 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 s only available
15980 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f if SQLite is co
15990 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 mpiled.** with e
159a0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e ither [SQLITE_EN
159b0 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 ABLE_MEMSYS3] or
159c0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
159d0 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 MEMSYS5] and ret
159e0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f urns.** [SQLITE_
159f0 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 ERROR] if invoke
15a00 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 d otherwise..**
15a10 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 ^There are three
15a20 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 arguments to SQ
15a30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
15a40 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 :.** An 8-byte a
15a50 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 ligned pointer t
15a60 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a o the memory,.**
15a70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
15a80 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f ytes in the memo
15a90 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 ry buffer, and t
15aa0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 he minimum alloc
15ab0 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e ation size..** ^
15ac0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 If the first poi
15ad0 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 nter (the memory
15ae0 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c pointer) is NUL
15af0 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 L, then SQLite r
15b00 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 everts.** to usi
15b10 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d ng its default m
15b20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
15b30 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c (the system mall
15b40 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 oc() implementat
15b50 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 ion),.** undoing
15b60 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 any prior invoc
15b70 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 ation of [SQLITE
15b80 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e _CONFIG_MALLOC].
15b90 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d ^If the.** mem
15ba0 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e ory pointer is n
15bb0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 ot NULL then the
15bc0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d alternative mem
15bd0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 ory.** allocator
15be0 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 is engaged to h
15bf0 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c andle all of SQL
15c00 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ites memory allo
15c10 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a cation needs..**
15c20 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 The first point
15c30 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 er (the memory p
15c40 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 ointer) must be
15c50 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d aligned to an 8-
15c60 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 byte.** boundary
15c70 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 or subsequent b
15c80 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 ehavior of SQLit
15c90 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 e will be undefi
15ca0 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 ned..** The mini
15cb0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 mum allocation s
15cc0 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 ize is capped at
15cd0 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 2**12. Reasonab
15ce0 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 le values.** for
15cf0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c the minimum all
15d00 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 ocation size are
15d10 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2**5 through 2*
15d20 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b *8.</dd>.**.** [
15d30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
15d40 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 UTEX]] <dt>SQLIT
15d50 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f E_CONFIG_MUTEX</
15d60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
15d70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
15d80 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b MUTEX option tak
15d90 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
15da0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a ment which is a.
15db0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e ** pointer to an
15dc0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
15dd0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
15de0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
15df0 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d re..** The argum
15e00 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c ent specifies al
15e10 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 ternative low-le
15e20 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e vel mutex routin
15e30 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a es to be used.**
15e40 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 in place the mu
15e50 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 tex routines bui
15e60 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 lt into SQLite.)
15e70 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 ^ ^SQLite makes
15e80 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 a copy of.** th
15e90 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
15ea0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
15eb0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
15ec0 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 re before the ca
15ed0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
15ee0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 3_config()] retu
15ef0 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 rns. ^If SQLite
15f00 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
15f10 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
15f20 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
15f30 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
15f40 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
15f50 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 ption then.** th
15f60 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e e entire mutexin
15f70 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f g subsystem is o
15f80 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 mitted from the
15f90 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 build and hence
15fa0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c calls to.** [sql
15fb0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
15fc0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 ith the SQLITE_C
15fd0 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 ONFIG_MUTEX conf
15fe0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
15ff0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 will.** return
16000 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c [SQLITE_ERROR].<
16010 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
16020 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
16030 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 TEX]] <dt>SQLITE
16040 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 _CONFIG_GETMUTEX
16050 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
16060 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
16070 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f G_GETMUTEX optio
16080 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
16090 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a argument which.
160a0 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ** is a pointer
160b0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
160c0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
160d0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 utex_methods] st
160e0 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a ructure. The.**
160f0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
16100 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 methods].** stru
16110 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 cture is filled
16120 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 with the current
16130 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 ly defined mutex
16140 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 routines.)^.**
16150 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 This option can
16160 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c be used to overl
16170 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 oad the default
16180 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e mutex allocation
16190 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 .** routines wit
161a0 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 h a wrapper used
161b0 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 to track mutex
161c0 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 usage for perfor
161d0 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 mance.** profili
161e0 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 ng or testing, f
161f0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 or example. ^I
16200 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
16210 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 iled with.** the
16220 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
16230 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 AFE | SQLITE_THR
16240 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 EADSAFE=0] compi
16250 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
16260 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 hen.** the entir
16270 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 e mutexing subsy
16280 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 stem is omitted
16290 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 from the build a
162a0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 nd hence calls t
162b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
162c0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 nfig()] with the
162d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
162e0 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 ETMUTEX configur
162f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c ation option wil
16300 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c l.** return [SQL
16310 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e ITE_ERROR].</dd>
16320 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
16330 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
16340 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
16350 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f NFIG_LOOKASIDE</
16360 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
16370 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16380 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e LOOKASIDE option
16390 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d takes two argum
163a0 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d ents that determ
163b0 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 ine.** the defau
163c0 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 lt size of looka
163d0 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 side memory on e
163e0 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f ach [database co
163f0 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 nnection]..** Th
16400 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
16410 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 is the.** size
16420 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 of each lookasid
16430 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e e buffer slot an
16440 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 d the second is
16450 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
16460 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 slots allocated
16470 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 to each databas
16480 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 e connection.)^
16490 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ^(SQLITE_CONFIG
164a0 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 _LOOKASIDE.** se
164b0 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c ts the <i>defaul
164c0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 t</i> lookaside
164d0 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 size. The [SQLIT
164e0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
164f0 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 SIDE].** option
16500 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 to [sqlite3_db_c
16510 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 onfig()] can be
16520 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 used to change t
16530 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 he lookaside.**
16540 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e configuration on
16550 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e individual conn
16560 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e ections.)^ </dd>
16570 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
16580 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d CONFIG_PCACHE2]]
16590 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
165a0 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a IG_PCACHE2</dt>.
165b0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
165c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
165d0 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 HE2 option takes
165e0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
165f0 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 nt which is .**
16600 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
16610 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
16620 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 methods2] object
16630 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 . This object s
16640 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 pecifies.** the
16650 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 interface to a c
16660 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 ustom page cache
16670 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
16680 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 )^.** ^SQLite ma
16690 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 kes a copy of th
166a0 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 e [sqlite3_pcach
166b0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 e_methods2] obje
166c0 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ct.</dd>.**.** [
166d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 [SQLITE_CONFIG_G
166e0 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e ETPCACHE2]] <dt>
166f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
16700 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a TPCACHE2</dt>.**
16710 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 <dd> ^(The SQLI
16720 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
16730 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 CHE2 option take
16740 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
16750 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ent which.** is
16760 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
16770 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
16780 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 methods2] object
16790 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 . SQLite copies
167a0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 of.** the curre
167b0 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d nt page cache im
167c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 plementation int
167d0 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e o that object.)^
167e0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
167f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
16800 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
16810 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a NFIG_LOG</dt>.**
16820 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 <dd> The SQLITE
16830 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 _CONFIG_LOG opti
16840 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f on is used to co
16850 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 nfigure the SQLi
16860 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 te.** global [er
16870 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 ror log]..** (^T
16880 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
16890 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 _LOG option take
168a0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a s two arguments:
168b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a a pointer to a.
168c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 ** function with
168d0 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 a call signatur
168e0 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 e of void(*)(voi
168f0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 d*,int,const cha
16900 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 r*), .** and a p
16910 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 ointer to void.
16920 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e ^If the function
16930 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 pointer is not
16940 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 NULL, it is.** i
16950 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 nvoked by [sqlit
16960 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f e3_log()] to pro
16970 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e cess each loggin
16980 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 g event. ^If th
16990 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f e.** function po
169a0 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 inter is NULL, t
169b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 he [sqlite3_log(
169c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 )] interface bec
169d0 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a omes a no-op..**
169e0 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 ^The void point
169f0 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 er that is the s
16a00 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
16a10 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f o SQLITE_CONFIG_
16a20 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 LOG is.** passed
16a30 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 through as the
16a40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
16a50 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 to the applicati
16a60 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 on-defined logge
16a70 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 r.** function wh
16a80 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 enever that func
16a90 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e tion is invoked.
16aa0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 ^The second pa
16ab0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 rameter to.** th
16ac0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f e logger functio
16ad0 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 n is a copy of t
16ae0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
16af0 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 er to the corres
16b00 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 ponding.** [sqli
16b10 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 te3_log()] call
16b20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 and is intended
16b30 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 to be a [result
16b40 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b code] or an.** [
16b50 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
16b60 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 code]. ^The thi
16b70 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 rd parameter pas
16b80 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 sed to the logge
16b90 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 r is.** log mess
16ba0 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 age after format
16bb0 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 ting via [sqlite
16bc0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 3_snprintf()]..*
16bd0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 * The SQLite log
16be0 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 ging interface i
16bf0 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b s not reentrant;
16c00 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 the logger func
16c10 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 tion.** supplied
16c20 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 by the applicat
16c30 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 ion must not inv
16c40 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 oke any SQLite i
16c50 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 nterface..** In
16c60 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 a multi-threaded
16c70 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 application, th
16c80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
16c90 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 fined logger.**
16ca0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 function must be
16cb0 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 threadsafe. </d
16cc0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
16cd0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c E_CONFIG_URI]] <
16ce0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
16cf0 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 _URI.** <dd>^(Th
16d00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16d10 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 URI option takes
16d20 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
16d30 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a nt of type int..
16d40 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 ** If non-zero,
16d50 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e then URI handlin
16d60 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e g is globally en
16d70 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 abled. If the pa
16d80 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c rameter is zero,
16d90 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e .** then URI han
16da0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c dling is globall
16db0 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 y disabled.)^ ^I
16dc0 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 f URI handling i
16dd0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e s globally.** en
16de0 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e abled, all filen
16df0 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b ames passed to [
16e00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
16e10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
16e20 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 2()],.** [sqlite
16e30 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 3_open16()] or.*
16e40 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 * specified as p
16e50 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 art of [ATTACH]
16e60 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 commands are int
16e70 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 erpreted as URIs
16e80 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 , regardless.**
16e90 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
16ea0 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 t the [SQLITE_OP
16eb0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 EN_URI] flag is
16ec0 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 set when the dat
16ed0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
16ee0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e ion is opened. ^
16ef0 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c If it is globall
16f00 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 y disabled, file
16f10 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c names are.** onl
16f20 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 y interpreted as
16f30 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c URIs if the SQL
16f40 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 ITE_OPEN_URI fla
16f50 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 g is set when th
16f60 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f e.** database co
16f70 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e nnection is open
16f80 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 ed. ^(By default
16f90 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 , URI handling i
16fa0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 s globally.** di
16fb0 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 sabled. The defa
16fc0 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 ult value may be
16fd0 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 changed by comp
16fe0 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a iling with the.*
16ff0 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 * [SQLITE_USE_UR
17000 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 I] symbol define
17010 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d.)^.**.** [[SQL
17020 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 ITE_CONFIG_COVER
17030 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d ING_INDEX_SCAN]]
17040 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
17050 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 IG_COVERING_INDE
17060 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 X_SCAN.** <dd>^T
17070 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
17080 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f _COVERING_INDEX_
17090 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 SCAN option take
170a0 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 s a single integ
170b0 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 er.** argument w
170c0 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 hich is interpre
170d0 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e ted as a boolean
170e0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 in order to ena
170f0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a ble or disable.*
17100 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 * the use of cov
17110 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f ering indices fo
17120 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 r full table sca
17130 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 ns in the query
17140 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 optimizer..** ^T
17150 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 he default setti
17160 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 ng is determined
17170 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 .** by the [SQLI
17180 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e TE_ALLOW_COVERIN
17190 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f G_INDEX_SCAN] co
171a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
171b0 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a n, or is "on".**
171c0 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 if that compile
171d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 -time option is
171e0 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 omitted..** The
171f0 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 ability to disab
17200 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f le the use of co
17210 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 vering indices f
17220 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 or full table sc
17230 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 ans.** is becaus
17240 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 e some incorrect
17250 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 ly coded legacy
17260 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 applications mig
17270 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a ht malfunction.*
17280 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d * when the optim
17290 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c ization is enabl
172a0 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 ed. Providing t
172b0 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a he ability to.**
172c0 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 disable the opt
172d0 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 imization allows
172e0 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 the older, bugg
172f0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f y application co
17300 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 de to work.** wi
17310 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 thout change eve
17320 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 n with newer ver
17330 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e sions of SQLite.
17340 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
17350 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 CONFIG_PCACHE]]
17360 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
17370 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c GETPCACHE]].** <
17380 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
17390 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 _PCACHE and SQLI
173a0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
173b0 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 CHE.** <dd> Thes
173c0 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 e options are ob
173d0 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c solete and shoul
173e0 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 d not be used by
173f0 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 new code..** Th
17400 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 ey are retained
17410 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f for backwards co
17420 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 mpatibility but
17430 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a are now no-ops..
17440 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ** </dd>.**.** [
17450 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
17460 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 QLLOG]].** <dt>S
17470 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c QLITE_CONFIG_SQL
17480 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 LOG.** <dd>This
17490 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 option is only a
174a0 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 vailable if sqli
174b0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
174c0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
174d0 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 TE_ENABLE_SQLLOG
174e0 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 ] pre-processor
174f0 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 macro defined. T
17500 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
17510 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 t should.** be a
17520 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 pointer to a fu
17530 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 nction of type v
17540 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
17550 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 ite3*,const char
17560 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 *, int)..** The
17570 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 second should be
17580 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 of type (void*)
17590 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 . The callback i
175a0 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 s invoked by the
175b0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 library.** in t
175c0 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 hree separate ci
175d0 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 rcumstances, ide
175e0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 ntified by the v
175f0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 alue passed as t
17600 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 he.** fourth par
17610 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 ameter. If the f
17620 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
17630 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 is 0, then the d
17640 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
17650 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 on.** passed as
17660 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
17670 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 ent has just bee
17680 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 n opened. The th
17690 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ird argument.**
176a0 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 points to a buff
176b0 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 er containing th
176c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 e name of the ma
176d0 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 in database file
176e0 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 . If the.** four
176f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
17700 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 1, then the SQL
17710 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 statement that t
17720 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
17730 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 er.** points to
17740 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 has just been ex
17750 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 ecuted. Or, if t
17760 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
17770 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a ter is 2, then.*
17780 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e * the connection
17790 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 being passed as
177a0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
177b0 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 meter is being c
177c0 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 losed. The.** th
177d0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ird parameter is
177e0 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 passed NULL In
177f0 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 this case. An e
17800 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 xample of using
17810 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 this.** configur
17820 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e ation option can
17830 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 be seen in the
17840 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 "test_sqllog.c"
17850 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a source file in.*
17860 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 * the canonical
17870 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 SQLite source tr
17880 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ee.</dd>.**.** [
17890 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
178a0 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 MAP_SIZE]].** <d
178b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
178c0 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 MMAP_SIZE.** <dd
178d0 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f >^SQLITE_CONFIG_
178e0 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 MMAP_SIZE takes
178f0 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 two 64-bit integ
17900 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 er (sqlite3_int6
17910 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 4) values.** tha
17920 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c t are the defaul
17930 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 t mmap size limi
17940 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 t (the default s
17950 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 etting for.** [P
17960 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d RAGMA mmap_size]
17970 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 ) and the maximu
17980 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 m allowed mmap s
17990 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 ize limit..** ^T
179a0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 he default setti
179b0 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 ng can be overri
179c0 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 dden by each dat
179d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
179e0 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 using.** either
179f0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 the [PRAGMA mma
17a00 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c p_size] command,
17a10 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 or by using the
17a20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 .** [SQLITE_FCNT
17a30 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c L_MMAP_SIZE] fil
17a40 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 e control. ^(Th
17a50 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 e maximum allowe
17a60 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 d mmap size.** w
17a70 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 ill be silently
17a80 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 truncated if nec
17a90 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 essary so that i
17aa0 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 t does not excee
17ab0 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 d the.** compile
17ac0 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d -time maximum mm
17ad0 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 ap size set by t
17ae0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 he.** [SQLITE_MA
17af0 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d X_MMAP_SIZE] com
17b00 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
17b10 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 .)^.** ^If eithe
17b20 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 r argument to th
17b30 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 is option is neg
17b40 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 ative, then that
17b50 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 argument is.**
17b60 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 changed to its c
17b70 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 ompile-time defa
17b80 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c ult..**.** [[SQL
17b90 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 ITE_CONFIG_WIN32
17ba0 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c _HEAPSIZE]].** <
17bb0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
17bc0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a _WIN32_HEAPSIZE.
17bd0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 ** <dd>^The SQLI
17be0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f TE_CONFIG_WIN32_
17bf0 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 HEAPSIZE option
17c00 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c is only availabl
17c10 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a e if SQLite is.*
17c20 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 * compiled for W
17c30 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 indows with the
17c40 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 [SQLITE_WIN32_MA
17c50 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 LLOC] pre-proces
17c60 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 sor macro.** def
17c70 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f ined. ^SQLITE_CO
17c80 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 NFIG_WIN32_HEAPS
17c90 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 IZE takes a 32-b
17ca0 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 it unsigned inte
17cb0 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 ger value.** tha
17cc0 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 t specifies the
17cd0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 maximum size of
17ce0 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70 the created heap
17cf0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ..**.** [[SQLITE
17d00 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 _CONFIG_PCACHE_H
17d10 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 DRSZ]].** <dt>SQ
17d20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
17d30 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e HE_HDRSZ.** <dd>
17d40 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
17d50 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 IG_PCACHE_HDRSZ
17d60 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
17d70 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 ingle parameter
17d80 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f which.** is a po
17d90 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
17da0 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 ger and writes i
17db0 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 nto that integer
17dc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 the number of e
17dd0 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 xtra.** bytes pe
17de0 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20 r page required
17df0 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e for each page in
17e00 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
17e10 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 PAGECACHE]..** T
17e20 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 he amount of ext
17e30 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65 ra space require
17e40 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 d can change dep
17e50 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f ending on the co
17e60 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 mpiler,.** targe
17e70 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 t platform, and
17e80 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a SQLite version..
17e90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
17ea0 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a ONFIG_PMASZ]].**
17eb0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
17ec0 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e IG_PMASZ.** <dd>
17ed0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
17ee0 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 IG_PMASZ option
17ef0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 takes a single p
17f00 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a arameter which.*
17f10 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 * is an unsigned
17f20 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 integer and set
17f30 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 s the "Minimum P
17f40 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 MA Size" for the
17f50 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a multithreaded.*
17f60 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 * sorter to that
17f70 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 integer. The d
17f80 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 efault minimum P
17f90 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 MA Size is set b
17fa0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 y the.** [SQLITE
17fb0 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 _SORTER_PMASZ] c
17fc0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
17fd0 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 on. New threads
17fe0 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a are launched.**
17ff0 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f to help with so
18000 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 rt operations wh
18010 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 en multithreaded
18020 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 sorting.** is e
18030 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 nabled (using th
18040 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 e [PRAGMA thread
18050 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 s] command) and
18060 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f the amount of co
18070 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 ntent.** to be s
18080 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68 orted exceeds th
18090 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 e page size time
180a0 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 s the minimum of
180b0 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 the.** [PRAGMA
180c0 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 cache_size] sett
180d0 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c ing and this val
180e0 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 ue..**.** [[SQLI
180f0 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 TE_CONFIG_STMTJR
18100 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 NL_SPILL]].** <d
18110 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
18120 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a STMTJRNL_SPILL.*
18130 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 * <dd>^The SQLIT
18140 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e E_CONFIG_STMTJRN
18150 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 L_SPILL option t
18160 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 akes a single pa
18170 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a rameter which.**
18180 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73 74 becomes the [st
18190 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d atement journal]
181a0 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 spill-to-disk t
181b0 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b hreshold. .** [
181c0 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 Statement journa
181d0 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e 20 ls] are held in
181e0 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68 65 memory until the
181f0 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74 65 ir size (in byte
18200 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74 68 s).** exceeds th
18210 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61 74 is threshold, at
18220 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68 65 which point the
18230 79 20 61 72 65 20 77 72 69 74 74 65 6e 20 74 6f y are written to
18240 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 disk..** Or if
18250 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69 73 the threshold is
18260 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a -1, statement j
18270 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77 61 ournals are alwa
18280 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 ys held.** exclu
18290 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 sively in memory
182a0 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20 ..** Since many
182b0 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 statement journa
182c0 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65 20 ls never become
182d0 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20 74 large, setting t
182e0 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 he spill.** thre
182f0 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75 65 shold to a value
18300 20 73 75 63 68 20 61 73 20 36 34 4b 69 42 20 63 such as 64KiB c
18310 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75 63 an greatly reduc
18320 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a e the amount of.
18330 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64 20 ** I/O required
18340 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74 65 to support state
18350 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a ment rollback..*
18360 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 * The default va
18370 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73 65 74 lue for this set
18380 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c ting is controll
18390 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 ed by the.** [SQ
183a0 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 LITE_STMTJRNL_SP
183b0 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d ILL] compile-tim
183c0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 e option..**.**
183d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
183e0 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 5d 5d SORTERREF_SIZE]]
183f0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
18400 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f ONFIG_SORTERREF_
18410 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 SIZE.** <dd>The
18420 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f SQLITE_CONFIG_SO
18430 52 54 45 52 52 45 46 5f 53 49 5a 45 20 6f 70 74 RTERREF_SIZE opt
18440 69 6f 6e 20 61 63 63 65 70 74 73 20 61 20 73 69 ion accepts a si
18450 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 0a 2a ngle parameter.*
18460 2a 20 6f 66 20 74 79 70 65 20 28 69 6e 74 29 20 * of type (int)
18470 2d 20 74 68 65 20 6e 65 77 20 76 61 6c 75 65 20 - the new value
18480 6f 66 20 74 68 65 20 73 6f 72 74 65 72 2d 72 65 of the sorter-re
18490 66 65 72 65 6e 63 65 20 73 69 7a 65 20 74 68 72 ference size thr
184a0 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55 73 75 61 6c eshold..** Usual
184b0 6c 79 2c 20 77 68 65 6e 20 53 51 4c 69 74 65 20 ly, when SQLite
184c0 75 73 65 73 20 61 6e 20 65 78 74 65 72 6e 61 6c uses an external
184d0 20 73 6f 72 74 20 74 6f 20 6f 72 64 65 72 20 72 sort to order r
184e0 65 63 6f 72 64 73 20 61 63 63 6f 72 64 69 6e 67 ecords according
184f0 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52 44 45 52 20 .** to an ORDER
18500 42 59 20 63 6c 61 75 73 65 2c 20 61 6c 6c 20 66 BY clause, all f
18510 69 65 6c 64 73 20 72 65 71 75 69 72 65 64 20 62 ields required b
18520 79 20 74 68 65 20 63 61 6c 6c 65 72 20 61 72 65 y the caller are
18530 20 70 72 65 73 65 6e 74 20 69 6e 20 74 68 65 0a present in the.
18540 2a 2a 20 73 6f 72 74 65 64 20 72 65 63 6f 72 64 ** sorted record
18550 73 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 s. However, if S
18560 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 QLite determines
18570 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20 64 65 based on the de
18580 63 6c 61 72 65 64 20 74 79 70 65 0a 2a 2a 20 6f clared type.** o
18590 66 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e f a table column
185a0 20 74 68 61 74 20 69 74 73 20 76 61 6c 75 65 73 that its values
185b0 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 are likely to b
185c0 65 20 76 65 72 79 20 6c 61 72 67 65 20 2d 20 6c e very large - l
185d0 61 72 67 65 72 0a 2a 2a 20 74 68 61 6e 20 74 68 arger.** than th
185e0 65 20 63 6f 6e 66 69 67 75 72 65 64 20 73 6f 72 e configured sor
185f0 74 65 72 2d 72 65 66 65 72 65 6e 63 65 20 73 69 ter-reference si
18600 7a 65 20 74 68 72 65 73 68 6f 6c 64 20 2d 20 74 ze threshold - t
18610 68 65 6e 20 61 20 72 65 66 65 72 65 6e 63 65 0a hen a reference.
18620 2a 2a 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 ** is stored in
18630 65 61 63 68 20 73 6f 72 74 65 64 20 72 65 63 6f each sorted reco
18640 72 64 20 61 6e 64 20 74 68 65 20 72 65 71 75 69 rd and the requi
18650 72 65 64 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 red column value
18660 73 20 6c 6f 61 64 65 64 0a 2a 2a 20 66 72 6f 6d s loaded.** from
18670 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 73 the database as
18680 20 72 65 63 6f 72 64 73 20 61 72 65 20 72 65 74 records are ret
18690 75 72 6e 65 64 20 69 6e 20 73 6f 72 74 65 64 20 urned in sorted
186a0 6f 72 64 65 72 2e 20 54 68 65 20 64 65 66 61 75 order. The defau
186b0 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72 20 lt.** value for
186c0 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 74 this option is t
186d0 6f 20 6e 65 76 65 72 20 75 73 65 20 74 68 69 73 o never use this
186e0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 53 optimization. S
186f0 70 65 63 69 66 79 69 6e 67 20 61 20 0a 2a 2a 20 pecifying a .**
18700 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 negative value f
18710 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 72 or this option r
18720 65 73 74 6f 72 65 73 20 74 68 65 20 64 65 66 61 estores the defa
18730 75 6c 74 20 62 65 68 61 76 69 6f 75 72 2e 0a 2a ult behaviour..*
18740 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 * This option is
18750 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 only available
18760 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d if SQLite is com
18770 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a piled with the.*
18780 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 * [SQLITE_ENABLE
18790 5f 53 4f 52 54 45 52 5f 52 45 46 45 52 45 4e 43 _SORTER_REFERENC
187a0 45 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 ES] compile-time
187b0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b option..**.** [
187c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
187d0 45 4d 44 42 5f 4d 41 58 53 49 5a 45 5d 5d 0a 2a EMDB_MAXSIZE]].*
187e0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
187f0 46 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a FIG_MEMDB_MAXSIZ
18800 45 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c E.** <dd>The SQL
18810 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 44 42 ITE_CONFIG_MEMDB
18820 5f 4d 41 58 53 49 5a 45 20 6f 70 74 69 6f 6e 20 _MAXSIZE option
18830 61 63 63 65 70 74 73 20 61 20 73 69 6e 67 6c 65 accepts a single
18840 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 5b 73 parameter.** [s
18850 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20 70 61 qlite3_int64] pa
18860 72 61 6d 65 74 65 72 20 77 68 69 63 68 20 69 73 rameter which is
18870 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 61 78 the default max
18880 69 6d 75 6d 20 73 69 7a 65 20 66 6f 72 20 61 6e imum size for an
18890 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61 in-memory.** da
188a0 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75 tabase created u
188b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 64 65 sing [sqlite3_de
188c0 73 65 72 69 61 6c 69 7a 65 28 29 5d 2e 20 20 54 serialize()]. T
188d0 68 69 73 20 64 65 66 61 75 6c 74 20 6d 61 78 69 his default maxi
188e0 6d 75 6d 0a 2a 2a 20 73 69 7a 65 20 63 61 6e 20 mum.** size can
188f0 62 65 20 61 64 6a 75 73 74 65 64 20 75 70 20 6f be adjusted up o
18900 72 20 64 6f 77 6e 20 66 6f 72 20 69 6e 64 69 76 r down for indiv
18910 69 64 75 61 6c 20 64 61 74 61 62 61 73 65 73 20 idual databases
18920 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 using the.** [SQ
18930 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f LITE_FCNTL_SIZE_
18940 4c 49 4d 49 54 5d 20 5b 73 71 6c 69 74 65 33 5f LIMIT] [sqlite3_
18950 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 7c 66 69 6c file_control|fil
18960 65 2d 63 6f 6e 74 72 6f 6c 5d 2e 20 20 49 66 20 e-control]. If
18970 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 this.** configur
18980 61 74 69 6f 6e 20 73 65 74 74 69 6e 67 20 69 73 ation setting is
18990 20 6e 65 76 65 72 20 75 73 65 64 2c 20 74 68 65 never used, the
189a0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 61 n the default ma
189b0 78 69 6d 75 6d 20 69 73 20 64 65 74 65 72 6d 69 ximum is determi
189c0 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 ned.** by the [S
189d0 51 4c 49 54 45 5f 4d 45 4d 44 42 5f 44 45 46 41 QLITE_MEMDB_DEFA
189e0 55 4c 54 5f 4d 41 58 53 49 5a 45 5d 20 63 6f 6d ULT_MAXSIZE] com
189f0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
18a00 2e 20 20 49 66 20 74 68 61 74 0a 2a 2a 20 63 6f . If that.** co
18a10 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
18a20 6e 20 69 73 20 6e 6f 74 20 73 65 74 2c 20 74 68 n is not set, th
18a30 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d en the default m
18a40 61 78 69 6d 75 6d 20 69 73 20 31 30 37 33 37 34 aximum is 107374
18a50 31 38 32 34 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 1824..** </dl>.*
18a60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18a70 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
18a80 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 READ 1 /* nil
18a90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18aa0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
18ab0 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c READ 2 /* nil
18ac0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18ad0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
18ae0 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 IZED 3 /* ni
18af0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
18b00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
18b10 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 C 4 /* s
18b20 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
18b30 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
18b40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
18b50 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a MALLOC 5 /*
18b60 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
18b70 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 hods* */.#define
18b80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
18b90 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 CRATCH 6
18ba0 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 /* No longer use
18bb0 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
18bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
18bd0 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 ACHE 7 /* v
18be0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e oid*, int sz, in
18bf0 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 t N */.#define S
18c00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
18c10 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a P 8 /*
18c20 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 void*, int nByt
18c30 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 e, int min */.#d
18c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
18c50 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 FIG_MEMSTATUS
18c60 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 9 /* boolean
18c70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18c80 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 E_CONFIG_MUTEX
18c90 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 10 /* sql
18ca0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
18cb0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
18cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
18cd0 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a MUTEX 11 /*
18ce0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
18cf0 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 ethods* */./* pr
18d00 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f eviously SQLITE_
18d10 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f CONFIG_CHUNKALLO
18d20 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f C 12 which is no
18d30 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 w unused. */ .#d
18d40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
18d50 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 FIG_LOOKASIDE
18d60 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 13 /* int int
18d70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18d80 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 E_CONFIG_PCACHE
18d90 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 14 /* no-
18da0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 op */.#define SQ
18db0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
18dc0 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 CACHE 15 /*
18dd0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 no-op */.#define
18de0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c SQLITE_CONFIG_L
18df0 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 OG 16
18e00 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 /* xFunc, void*
18e10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18e20 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 E_CONFIG_URI
18e30 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 17 /* int
18e40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18e50 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
18e60 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 2 18 /* sq
18e70 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
18e80 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e hods2* */.#defin
18e90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
18ea0 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 GETPCACHE2 19
18eb0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 /* sqlite3_pcac
18ec0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a he_methods2* */.
18ed0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
18ee0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 ONFIG_COVERING_I
18ef0 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a NDEX_SCAN 20 /*
18f00 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
18f10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 SQLITE_CONFIG_SQ
18f20 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f LLOG 21 /
18f30 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a * xSqllog, void*
18f40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18f50 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 TE_CONFIG_MMAP_S
18f60 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 IZE 22 /* sq
18f70 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c lite3_int64, sql
18f80 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 ite3_int64 */.#d
18f90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
18fa0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 FIG_WIN32_HEAPSI
18fb0 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 ZE 23 /* i
18fc0 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 nt nByte */.#def
18fd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
18fe0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 G_PCACHE_HDRSZ
18ff0 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 24 /* int
19000 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 *psz */.#define
19010 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
19020 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 MASZ
19030 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 25 /* unsign
19040 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a ed int szPma */.
19050 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
19060 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 ONFIG_STMTJRNL_S
19070 50 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a PILL 26 /*
19080 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 int nByte */.#d
19090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
190a0 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 FIG_SMALL_MALLOC
190b0 20 20 20 20 20 20 20 20 32 37 20 20 2f 2a 20 62 27 /* b
190c0 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e oolean */.#defin
190d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
190e0 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 20 20 SORTERREF_SIZE
190f0 20 20 20 20 32 38 20 20 2f 2a 20 69 6e 74 20 6e 28 /* int n
19100 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 Byte */.#define
19110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
19120 4d 44 42 5f 4d 41 58 53 49 5a 45 20 20 20 20 20 MDB_MAXSIZE
19130 20 20 32 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 29 /* sqlite3
19140 5f 69 6e 74 36 34 20 2a 2f 0a 0a 2f 2a 0a 2a 2a _int64 */../*.**
19150 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 CAPI3REF: Datab
19160 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 ase Connection C
19170 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 onfiguration Opt
19180 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
19190 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 constants are t
191a0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 he available int
191b0 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 eger configurati
191c0 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a on options that.
191d0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 ** can be passed
191e0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 as the second a
191f0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b rgument to the [
19200 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
19210 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a g()] interface..
19220 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 **.** New config
19230 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
19240 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
19250 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
19260 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 of SQLite..** Ex
19270 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 isting configura
19280 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 tion options mig
19290 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 ht be discontinu
192a0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e ed. Application
192b0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 s.** should chec
192c0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 k the return cod
192d0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f e from [sqlite3_
192e0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 db_config()] to
192f0 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a make sure that.*
19300 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 * the call worke
19310 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 d. ^The [sqlite
19320 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 3_db_config()] i
19330 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 nterface will re
19340 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 turn a.** non-ze
19350 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ro [error code]
19360 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 if a discontinue
19370 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 d or unsupported
19380 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
19390 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f ption.** is invo
193a0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ked..**.** <dl>.
193b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f ** [[SQLITE_DBCO
193c0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d NFIG_LOOKASIDE]]
193d0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
193e0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
193f0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e E</dt>.** <dd> ^
19400 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
19410 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e s three addition
19420 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 al arguments tha
19430 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 t determine the
19440 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d .** [lookaside m
19450 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d emory allocator]
19460 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 configuration f
19470 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 or the [database
19480 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
19490 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 ^The first argu
194a0 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 ment (the third
194b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
194c0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
194d0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 )] is a.** point
194e0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 er to a memory b
194f0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 uffer to use for
19500 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
19510 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 y..** ^The first
19520 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 argument after
19530 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e the SQLITE_DBCON
19540 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 FIG_LOOKASIDE ve
19550 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c rb.** may be NUL
19560 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 L in which case
19570 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f SQLite will allo
19580 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b cate the.** look
19590 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 aside buffer its
195a0 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 elf using [sqlit
195b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 e3_malloc()]. ^T
195c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
195d0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a nt is the.** siz
195e0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 e of each lookas
195f0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e ide buffer slot.
19600 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 ^The third arg
19610 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d ument is the num
19620 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e ber of.** slots.
19630 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 The size of th
19640 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 e buffer in the
19650 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d first argument m
19660 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 ust be greater t
19670 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 han.** or equal
19680 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f to the product o
19690 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 f the second and
196a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 third arguments
196b0 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a . The buffer.**
196c0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 must be aligned
196d0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f to an 8-byte bo
196e0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 undary. ^If the
196f0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
19700 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 to.** SQLITE_DB
19710 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
19720 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 is not a multip
19730 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 le of 8, it is i
19740 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 nternally.** rou
19750 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 nded down to the
19760 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 next smaller mu
19770 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 ltiple of 8. ^(
19780 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 The lookaside me
19790 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 mory.** configur
197a0 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 ation for a data
197b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
197c0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e can only be chan
197d0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a ged when that.**
197e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e connection is n
197f0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 ot currently usi
19800 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d ng lookaside mem
19810 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 ory, or in other
19820 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 words.** when t
19830 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 he "current valu
19840 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a e" returned by.*
19850 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 * [sqlite3_db_st
19860 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f atus](D,[SQLITE_
19870 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
19880 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a ],...) is zero..
19890 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 ** Any attempt t
198a0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f o change the loo
198b0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f kaside memory co
198c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e nfiguration when
198d0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 lookaside.** me
198e0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c mory is in use l
198f0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 eaves the config
19900 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 uration unchange
19910 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a d and returns .*
19920 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e * [SQLITE_BUSY].
19930 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b )^</dd>.**.** [[
19940 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
19950 45 4e 41 42 4c 45 5f 46 4b 45 59 5d 5d 0a 2a 2a ENABLE_FKEY]].**
19960 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
19970 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 NFIG_ENABLE_FKEY
19980 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
19990 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 his option is us
199a0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 ed to enable or
199b0 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f disable the enfo
199c0 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 rcement of.** [f
199d0 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 oreign key const
199e0 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 raints]. There
199f0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 should be two ad
19a00 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e ditional argumen
19a10 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 ts..** The first
19a20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 argument is an
19a30 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 integer which is
19a40 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 0 to disable FK
19a50 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a enforcement,.**
19a60 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 positive to ena
19a70 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 ble FK enforceme
19a80 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 nt or negative t
19a90 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 o leave FK enfor
19aa0 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e cement.** unchan
19ab0 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 ged. The second
19ac0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
19ad0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
19ae0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 teger into which
19af0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 .** is written 0
19b00 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 or 1 to indicat
19b10 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 e whether FK enf
19b20 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 orcement is off
19b30 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 or on.** followi
19b40 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 ng this call. T
19b50 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
19b60 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c ter may be a NUL
19b70 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a L pointer, in.**
19b80 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 which case the
19b90 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 FK enforcement s
19ba0 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 etting is not re
19bb0 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 ported back. </d
19bc0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
19bd0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
19be0 45 5f 54 52 49 47 47 45 52 5d 5d 0a 2a 2a 20 3c E_TRIGGER]].** <
19bf0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
19c00 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 IG_ENABLE_TRIGGE
19c10 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e R</dt>.** <dd> ^
19c20 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 This option is u
19c30 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 sed to enable or
19c40 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 disable [CREATE
19c50 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 TRIGGER | trigg
19c60 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 ers]..** There s
19c70 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 hould be two add
19c80 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
19c90 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 s..** The first
19ca0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 argument is an i
19cb0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 nteger which is
19cc0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 0 to disable tri
19cd0 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 ggers,.** positi
19ce0 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 ve to enable tri
19cf0 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 ggers or negativ
19d00 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 e to leave the s
19d10 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 etting unchanged
19d20 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
19d30 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
19d40 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
19d50 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a eger into which.
19d60 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 ** is written 0
19d70 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 or 1 to indicate
19d80 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 whether trigger
19d90 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f s are disabled o
19da0 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c r enabled.** fol
19db0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c lowing this call
19dc0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . The second pa
19dd0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 rameter may be a
19de0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 NULL pointer, i
19df0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 n.** which case
19e00 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 the trigger sett
19e10 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 ing is not repor
19e20 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a ted back. </dd>.
19e30 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 **.** [[SQLITE_D
19e40 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 56 BCONFIG_ENABLE_V
19e50 49 45 57 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c IEW]].** <dt>SQL
19e60 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
19e70 42 4c 45 5f 56 49 45 57 3c 2f 64 74 3e 0a 2a 2a BLE_VIEW</dt>.**
19e80 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
19e90 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e on is used to en
19ea0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 able or disable
19eb0 5b 43 52 45 41 54 45 20 56 49 45 57 20 7c 20 76 [CREATE VIEW | v
19ec0 69 65 77 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 iews]..** There
19ed0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 should be two ad
19ee0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e ditional argumen
19ef0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 ts..** The first
19f00 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 argument is an
19f10 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 integer which is
19f20 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 76 69 0 to disable vi
19f30 65 77 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 ews,.** positive
19f40 20 74 6f 20 65 6e 61 62 6c 65 20 76 69 65 77 73 to enable views
19f50 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 or negative to
19f60 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e leave the settin
19f70 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 g unchanged..**
19f80 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
19f90 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 eter is a pointe
19fa0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 r to an integer
19fb0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 into which.** is
19fc0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 written 0 or 1
19fd0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 to indicate whet
19fe0 68 65 72 20 76 69 65 77 73 20 61 72 65 20 64 69 her views are di
19ff0 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 sabled or enable
1a000 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 d.** following t
1a010 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 his call. The s
1a020 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1a030 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f may be a NULL po
1a040 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 inter, in.** whi
1a050 63 68 20 63 61 73 65 20 74 68 65 20 76 69 65 77 ch case the view
1a060 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 setting is not
1a070 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c reported back. <
1a080 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
1a090 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
1a0a0 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a BLE_FTS3_TOKENIZ
1a0b0 45 52 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 ER]].** <dt>SQLI
1a0c0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
1a0d0 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 LE_FTS3_TOKENIZE
1a0e0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e R</dt>.** <dd> ^
1a0f0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 This option is u
1a100 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 sed to enable or
1a110 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 disable the.**
1a120 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 [fts3_tokenizer(
1a130 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63 )] function whic
1a140 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 h is part of the
1a150 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d .** [FTS3] full-
1a160 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67 69 text search engi
1a170 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a ne extension..**
1a180 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 There should be
1a190 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 two additional
1a1a0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 arguments..** Th
1a1b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
1a1c0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 is an integer w
1a1d0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 hich is 0 to dis
1a1e0 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 able fts3_tokeni
1a1f0 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69 zer() or.** posi
1a200 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66 tive to enable f
1a210 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 ts3_tokenizer()
1a220 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c or negative to l
1a230 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 eave the setting
1a240 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a .** unchanged..*
1a250 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 * The second par
1a260 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e ameter is a poin
1a270 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
1a280 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 r into which.**
1a290 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 is written 0 or
1a2a0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 1 to indicate wh
1a2b0 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e ether fts3_token
1a2c0 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 izer is disabled
1a2d0 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 or enabled.** f
1a2e0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 ollowing this ca
1a2f0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ll. The second
1a300 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
1a310 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
1a320 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 in.** which cas
1a330 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e e the new settin
1a340 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 g is not reporte
1a350 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a d back. </dd>.**
1a360 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 .** [[SQLITE_DBC
1a370 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 ONFIG_ENABLE_LOA
1a380 44 5f 45 58 54 45 4e 53 49 4f 4e 5d 5d 0a 2a 2a D_EXTENSION]].**
1a390 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
1a3a0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 NFIG_ENABLE_LOAD
1a3b0 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a _EXTENSION</dt>.
1a3c0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
1a3d0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
1a3e0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
1a3f0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c e the [sqlite3_l
1a400 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d oad_extension()]
1a410 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e .** interface in
1a420 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 dependently of t
1a430 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 he [load_extensi
1a440 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 on()] SQL functi
1a450 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 on..** The [sqli
1a460 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f te3_enable_load_
1a470 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 extension()] API
1a480 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
1a490 62 6c 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a bles both the.**
1a4a0 20 43 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f C-API [sqlite3_
1a4b0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
1a4c0 5d 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 ] and the SQL fu
1a4d0 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 nction [load_ext
1a4e0 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 ension()]..** Th
1a4f0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 ere should be tw
1a500 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 o additional arg
1a510 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 uments..** When
1a520 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
1a530 6e 74 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 nt to this inter
1a540 66 61 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20 face is 1, then
1a550 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69 only the C-API i
1a560 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 s.** enabled and
1a570 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
1a580 6e 20 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c n remains disabl
1a590 65 64 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 ed. If the firs
1a5a0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a t argument to.**
1a5b0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
1a5c0 69 73 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 is 0, then both
1a5d0 74 68 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 the C-API and th
1a5e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 e SQL function a
1a5f0 72 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 re disabled..**
1a600 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67 If the first arg
1a610 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 ument is -1, the
1a620 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 n no changes are
1a630 20 6d 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f made to state o
1a640 66 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 f either the.**
1a650 43 2d 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c C-API or the SQL
1a660 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 function..** Th
1a670 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
1a680 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 er is a pointer
1a690 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e to an integer in
1a6a0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 to which.** is w
1a6b0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f ritten 0 or 1 to
1a6c0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 indicate whethe
1a6d0 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f r [sqlite3_load_
1a6e0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 extension()] int
1a6f0 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 erface.** is dis
1a700 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 abled or enabled
1a710 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 following this
1a720 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e call. The secon
1a730 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a d parameter may.
1a740 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 ** be a NULL poi
1a750 6e 74 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 nter, in which c
1a760 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 ase the new sett
1a770 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 ing is not repor
1a780 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 ted back..** </d
1a790 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
1a7a0 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 E_DBCONFIG_MAIND
1a7b0 42 4e 41 4d 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 BNAME]] <dt>SQLI
1a7c0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e TE_DBCONFIG_MAIN
1a7d0 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c DBNAME</dt>.** <
1a7e0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
1a7f0 20 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e is used to chan
1a800 67 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ge the name of t
1a810 68 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61 he "main" databa
1a820 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e se.** schema. ^
1a830 54 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e The sole argumen
1a840 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
1a850 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 o a constant UTF
1a860 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 8 string.** whic
1a870 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 h will become th
1a880 65 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d e new schema nam
1a890 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d e in place of "m
1a8a0 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a ain". ^SQLite.*
1a8b0 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 * does not make
1a8c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 a copy of the ne
1a8d0 77 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 w main schema na
1a8e0 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 me string, so th
1a8f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a e application.**
1a900 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 must ensure tha
1a910 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 t the argument p
1a920 61 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20 assed into this
1a930 44 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 DBCONFIG option
1a940 69 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 is unchanged.**
1a950 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20 until after the
1a960 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1a970 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c ion closes..** <
1a980 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
1a990 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f ITE_DBCONFIG_NO_
1a9a0 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 5d 5d 20 CKPT_ON_CLOSE]]
1a9b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
1a9c0 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f BCONFIG_NO_CKPT_
1a9d0 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a ON_CLOSE</dt>.**
1a9e0 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 <dd> Usually, w
1a9f0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 hen a database i
1aa00 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c n wal mode is cl
1aa10 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 osed or detached
1aa20 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 from a .** data
1aa30 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c base handle, SQL
1aa40 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 ite checks if th
1aa50 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 is will mean tha
1aa60 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 t there are now
1aa70 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f no .** connectio
1aa80 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 ns at all to the
1aa90 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f database. If so
1aaa0 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 , it performs a
1aab0 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f checkpoint .** o
1aac0 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 peration before
1aad0 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e closing the conn
1aae0 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 ection. This opt
1aaf0 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 ion may be used
1ab00 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 to.** override t
1ab10 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 his behaviour. T
1ab20 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
1ab30 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 er passed to thi
1ab40 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 s operation.** i
1ab50 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 70 s an integer - p
1ab60 6f 73 69 74 69 76 65 20 74 6f 20 64 69 73 61 62 ositive to disab
1ab70 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f le checkpoints-o
1ab80 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f n-close, or zero
1ab90 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 (the.** default
1aba0 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d ) to enable them
1abb0 2c 20 61 6e 64 20 6e 65 67 61 74 69 76 65 20 74 , and negative t
1abc0 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 o leave the sett
1abd0 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a ing unchanged..*
1abe0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 * The second par
1abf0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e ameter is a poin
1ac00 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
1ac10 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 r.** into which
1ac20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 is written 0 or
1ac30 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 1 to indicate wh
1ac40 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 ether checkpoint
1ac50 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 s-on-close.** ha
1ac60 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 ve been disabled
1ac70 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65 - 0 if they are
1ac80 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 not disabled, 1
1ac90 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a if they are..**
1aca0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
1acb0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
1acc0 4e 41 42 4c 45 5f 51 50 53 47 5d 5d 20 3c 64 74 NABLE_QPSG]] <dt
1acd0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 >SQLITE_DBCONFIG
1ace0 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 _ENABLE_QPSG</dt
1acf0 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 >.** <dd>^(The S
1ad00 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
1ad10 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f NABLE_QPSG optio
1ad20 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 n activates or d
1ad30 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 eactivates.** th
1ad40 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 e [query planner
1ad50 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72 61 stability guara
1ad60 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57 ntee] (QPSG). W
1ad70 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73 20 hen the QPSG is
1ad80 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e active,.** a sin
1ad90 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73 74 gle SQL query st
1ada0 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 atement will alw
1adb0 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65 ays use the same
1adc0 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72 algorithm regar
1add0 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 dless.** of valu
1ade0 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 es of [bound par
1adf0 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 ameters].)^ The
1ae00 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f QPSG disables so
1ae10 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a me query optimiz
1ae20 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c ations.** that l
1ae30 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65 ook at the value
1ae40 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d s of bound param
1ae50 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e eters, which can
1ae60 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 make some queri
1ae70 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 es.** slower. B
1ae80 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73 20 ut the QPSG has
1ae90 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66 the advantage of
1aea0 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c more predictabl
1aeb0 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74 e behavior. Wit
1aec0 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63 h.** the QPSG ac
1aed0 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c tive, SQLite wil
1aee0 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 l always use the
1aef0 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e same query plan
1af00 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73 in the field as
1af10 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75 72 .** was used dur
1af20 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74 ing testing in t
1af30 68 65 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66 he lab..** The f
1af40 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
1af50 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 this setting is
1af60 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 an integer whic
1af70 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c h is 0 to disabl
1af80 65 20 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c 20 e .** the QPSG,
1af90 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 positive to enab
1afa0 6c 65 20 51 50 53 47 2c 20 6f 72 20 6e 65 67 61 le QPSG, or nega
1afb0 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 tive to leave th
1afc0 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 e setting.** unc
1afd0 68 61 6e 67 65 64 2e 20 54 68 65 20 73 65 63 6f hanged. The seco
1afe0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
1aff0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
1b000 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 integer into whi
1b010 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e ch.** is written
1b020 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 0 or 1 to indic
1b030 61 74 65 20 77 68 65 74 68 65 72 20 74 68 65 20 ate whether the
1b040 51 50 53 47 20 69 73 20 64 69 73 61 62 6c 65 64 QPSG is disabled
1b050 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 or enabled.** f
1b060 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 ollowing this ca
1b070 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a ll..** </dd>.**.
1b080 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f ** [[SQLITE_DBCO
1b090 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 NFIG_TRIGGER_EQP
1b0a0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 ]] <dt>SQLITE_DB
1b0b0 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 CONFIG_TRIGGER_E
1b0c0 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 QP</dt>.** <dd>
1b0d0 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 By default, the
1b0e0 6f 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49 output of EXPLAI
1b0f0 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d N QUERY PLAN com
1b100 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a mands does not .
1b110 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75 ** include outpu
1b120 74 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74 t for any operat
1b130 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62 ions performed b
1b140 79 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 y trigger progra
1b150 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69 ms. This.** opti
1b160 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 on is used to se
1b170 74 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20 t or clear (the
1b180 64 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20 default) a flag
1b190 74 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69 that governs thi
1b1a0 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54 s.** behavior. T
1b1b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
1b1c0 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 er passed to thi
1b1d0 73 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 s operation is a
1b1e0 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70 n integer -.** p
1b1f0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c ositive to enabl
1b200 65 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69 e output for tri
1b210 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f gger programs, o
1b220 72 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c r zero to disabl
1b230 65 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61 e it,.** or nega
1b240 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 tive to leave th
1b250 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e e setting unchan
1b260 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f ged..** The seco
1b270 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
1b280 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
1b290 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 integer into whi
1b2a0 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a ch is written .*
1b2b0 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 * 0 or 1 to indi
1b2c0 63 61 74 65 20 77 68 65 74 68 65 72 20 6f 75 74 cate whether out
1b2d0 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73 put-for-triggers
1b2e0 20 68 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c has been disabl
1b2f0 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74 ed - 0 if .** it
1b300 20 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 is not disabled
1b310 2c 20 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a , 1 if it is. .
1b320 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ** </dd>.**.** [
1b330 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 [SQLITE_DBCONFIG
1b340 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 5d _RESET_DATABASE]
1b350 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 ] <dt>SQLITE_DBC
1b360 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 ONFIG_RESET_DATA
1b370 42 41 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 BASE</dt>.** <dd
1b380 3e 20 53 65 74 20 74 68 65 20 53 51 4c 49 54 45 > Set the SQLITE
1b390 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f _DBCONFIG_RESET_
1b3a0 44 41 54 41 42 41 53 45 20 66 6c 61 67 20 61 6e DATABASE flag an
1b3b0 64 20 74 68 65 6e 20 72 75 6e 0a 2a 2a 20 5b 56 d then run.** [V
1b3c0 41 43 55 55 4d 5d 20 69 6e 20 6f 72 64 65 72 20 ACUUM] in order
1b3d0 74 6f 20 72 65 73 65 74 20 61 20 64 61 74 61 62 to reset a datab
1b3e0 61 73 65 20 62 61 63 6b 20 74 6f 20 61 6e 20 65 ase back to an e
1b3f0 6d 70 74 79 20 64 61 74 61 62 61 73 65 0a 2a 2a mpty database.**
1b400 20 77 69 74 68 20 6e 6f 20 73 63 68 65 6d 61 20 with no schema
1b410 61 6e 64 20 6e 6f 20 63 6f 6e 74 65 6e 74 2e 20 and no content.
1b420 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 The following pr
1b430 6f 63 65 73 73 20 77 6f 72 6b 73 20 65 76 65 6e ocess works even
1b440 20 66 6f 72 0a 2a 2a 20 61 20 62 61 64 6c 79 20 for.** a badly
1b450 63 6f 72 72 75 70 74 65 64 20 64 61 74 61 62 61 corrupted databa
1b460 73 65 20 66 69 6c 65 3a 0a 2a 2a 20 3c 6f 6c 3e se file:.** <ol>
1b470 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 74 68 65 20 .** <li> If the
1b480 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1b490 69 6f 6e 20 69 73 20 6e 65 77 6c 79 20 6f 70 65 ion is newly ope
1b4a0 6e 65 64 2c 20 6d 61 6b 65 20 73 75 72 65 20 69 ned, make sure i
1b4b0 74 20 68 61 73 20 72 65 61 64 20 74 68 65 0a 2a t has read the.*
1b4c0 2a 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20 * database
1b4d0 73 63 68 65 6d 61 20 62 79 20 70 72 65 70 61 72 schema by prepar
1b4e0 69 6e 67 20 74 68 65 6e 20 64 69 73 63 61 72 64 ing then discard
1b4f0 69 6e 67 20 73 6f 6d 65 20 71 75 65 72 79 20 61 ing some query a
1b500 67 61 69 6e 73 74 20 74 68 65 0a 2a 2a 20 20 20 gainst the.**
1b510 20 20 20 64 61 74 61 62 61 73 65 2c 20 6f 72 20 database, or
1b520 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f calling sqlite3_
1b530 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 table_column_met
1b540 61 64 61 74 61 28 29 2c 20 69 67 6e 6f 72 69 6e adata(), ignorin
1b550 67 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 65 72 g any.** er
1b560 72 6f 72 73 2e 20 20 54 68 69 73 20 73 74 65 70 rors. This step
1b570 20 69 73 20 6f 6e 6c 79 20 6e 65 63 65 73 73 61 is only necessa
1b580 72 79 20 69 66 20 74 68 65 20 61 70 70 6c 69 63 ry if the applic
1b590 61 74 69 6f 6e 20 64 65 73 69 72 65 73 20 74 6f ation desires to
1b5a0 20 6b 65 65 70 0a 2a 2a 20 20 20 20 20 20 74 68 keep.** th
1b5b0 65 20 64 61 74 61 62 61 73 65 20 69 6e 20 57 41 e database in WA
1b5c0 4c 20 6d 6f 64 65 20 61 66 74 65 72 20 74 68 65 L mode after the
1b5d0 20 72 65 73 65 74 20 69 66 20 69 74 20 77 61 73 reset if it was
1b5e0 20 69 6e 20 57 41 4c 20 6d 6f 64 65 20 62 65 66 in WAL mode bef
1b5f0 6f 72 65 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 ore.** the
1b600 72 65 73 65 74 2e 20 20 0a 2a 2a 20 3c 6c 69 3e reset. .** <li>
1b610 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
1b620 69 67 28 64 62 2c 20 53 51 4c 49 54 45 5f 44 42 ig(db, SQLITE_DB
1b630 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 CONFIG_RESET_DAT
1b640 41 42 41 53 45 2c 20 31 2c 20 30 29 3b 0a 2a 2a ABASE, 1, 0);.**
1b650 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 65 <li> [sqlite3_e
1b660 78 65 63 5d 28 64 62 2c 20 22 5b 56 41 43 55 55 xec](db, "[VACUU
1b670 4d 5d 22 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a M]", 0, 0, 0);.*
1b680 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64 * <li> sqlite3_d
1b690 62 5f 63 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c b_config(db, SQL
1b6a0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 ITE_DBCONFIG_RES
1b6b0 45 54 5f 44 41 54 41 42 41 53 45 2c 20 30 2c 20 ET_DATABASE, 0,
1b6c0 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 20 0);.** </ol>.**
1b6d0 42 65 63 61 75 73 65 20 72 65 73 65 74 74 69 6e Because resettin
1b6e0 67 20 61 20 64 61 74 61 62 61 73 65 20 69 73 20 g a database is
1b6f0 64 65 73 74 72 75 63 74 69 76 65 20 61 6e 64 20 destructive and
1b700 69 72 72 65 76 65 72 73 69 62 6c 65 2c 20 74 68 irreversible, th
1b710 65 0a 2a 2a 20 70 72 6f 63 65 73 73 20 72 65 71 e.** process req
1b720 75 69 72 65 73 20 74 68 65 20 75 73 65 20 6f 66 uires the use of
1b730 20 74 68 69 73 20 6f 62 73 63 75 72 65 20 41 50 this obscure AP
1b740 49 20 61 6e 64 20 6d 75 6c 74 69 70 6c 65 20 73 I and multiple s
1b750 74 65 70 73 20 74 6f 20 68 65 6c 70 0a 2a 2a 20 teps to help.**
1b760 65 6e 73 75 72 65 20 74 68 61 74 20 69 74 20 64 ensure that it d
1b770 6f 65 73 20 6e 6f 74 20 68 61 70 70 65 6e 20 62 oes not happen b
1b780 79 20 61 63 63 69 64 65 6e 74 2e 0a 2a 2a 0a 2a y accident..**.*
1b790 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e * [[SQLITE_DBCON
1b7a0 46 49 47 5f 44 45 46 45 4e 53 49 56 45 5d 5d 20 FIG_DEFENSIVE]]
1b7b0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e <dt>SQLITE_DBCON
1b7c0 46 49 47 5f 44 45 46 45 4e 53 49 56 45 3c 2f 64 FIG_DEFENSIVE</d
1b7d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 t>.** <dd>The SQ
1b7e0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 45 LITE_DBCONFIG_DE
1b7f0 46 45 4e 53 49 56 45 20 6f 70 74 69 6f 6e 20 61 FENSIVE option a
1b800 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 ctivates or deac
1b810 74 69 76 61 74 65 73 20 74 68 65 0a 2a 2a 20 22 tivates the.** "
1b820 64 65 66 65 6e 73 69 76 65 22 20 66 6c 61 67 20 defensive" flag
1b830 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 for a database c
1b840 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 57 68 65 6e onnection. When
1b850 20 74 68 65 20 64 65 66 65 6e 73 69 76 65 0a 2a the defensive.*
1b860 2a 20 66 6c 61 67 20 69 73 20 65 6e 61 62 6c 65 * flag is enable
1b870 64 2c 20 6c 61 6e 67 75 61 67 65 20 66 65 61 74 d, language feat
1b880 75 72 65 73 20 74 68 61 74 20 61 6c 6c 6f 77 20 ures that allow
1b890 6f 72 64 69 6e 61 72 79 20 53 51 4c 20 74 6f 20 ordinary SQL to
1b8a0 0a 2a 2a 20 64 65 6c 69 62 65 72 61 74 65 6c 79 .** deliberately
1b8b0 20 63 6f 72 72 75 70 74 20 74 68 65 20 64 61 74 corrupt the dat
1b8c0 61 62 61 73 65 20 66 69 6c 65 20 61 72 65 20 64 abase file are d
1b8d0 69 73 61 62 6c 65 64 2e 20 20 54 68 65 20 64 69 isabled. The di
1b8e0 73 61 62 6c 65 64 0a 2a 2a 20 66 65 61 74 75 72 sabled.** featur
1b8f0 65 73 20 69 6e 63 6c 75 64 65 20 62 75 74 20 61 es include but a
1b900 72 65 20 6e 6f 74 20 6c 69 6d 69 74 65 64 20 74 re not limited t
1b910 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a o the following:
1b920 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
1b930 20 54 68 65 20 5b 50 52 41 47 4d 41 20 77 72 69 The [PRAGMA wri
1b940 74 61 62 6c 65 5f 73 63 68 65 6d 61 3d 4f 4e 5d table_schema=ON]
1b950 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 3c statement..** <
1b960 6c 69 3e 20 54 68 65 20 5b 50 52 41 47 4d 41 20 li> The [PRAGMA
1b970 6a 6f 75 72 6e 61 6c 5f 6d 6f 64 65 3d 4f 46 46 journal_mode=OFF
1b980 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 ] statement..**
1b990 3c 6c 69 3e 20 57 72 69 74 65 73 20 74 6f 20 74 <li> Writes to t
1b9a0 68 65 20 5b 73 71 6c 69 74 65 5f 64 62 70 61 67 he [sqlite_dbpag
1b9b0 65 5d 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 e] virtual table
1b9c0 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 69 72 65 63 74 ..** <li> Direct
1b9d0 20 77 72 69 74 65 73 20 74 6f 20 5b 73 68 61 64 writes to [shad
1b9e0 6f 77 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 3c ow tables]..** <
1b9f0 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a /ul>.** </dd>.**
1ba00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 .** [[SQLITE_DBC
1ba10 4f 4e 46 49 47 5f 57 52 49 54 41 42 4c 45 5f 53 ONFIG_WRITABLE_S
1ba20 43 48 45 4d 41 5d 5d 20 3c 64 74 3e 53 51 4c 49 CHEMA]] <dt>SQLI
1ba30 54 45 5f 44 42 43 4f 4e 46 49 47 5f 57 52 49 54 TE_DBCONFIG_WRIT
1ba40 41 42 4c 45 5f 53 43 48 45 4d 41 3c 2f 64 74 3e ABLE_SCHEMA</dt>
1ba50 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 .** <dd>The SQLI
1ba60 54 45 5f 44 42 43 4f 4e 46 49 47 5f 57 52 49 54 TE_DBCONFIG_WRIT
1ba70 41 42 4c 45 5f 53 43 48 45 4d 41 20 6f 70 74 69 ABLE_SCHEMA opti
1ba80 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 on activates or
1ba90 64 65 61 63 74 69 76 61 74 65 73 20 74 68 65 0a deactivates the.
1baa0 2a 2a 20 22 77 72 69 74 61 62 6c 65 5f 73 63 68 ** "writable_sch
1bab0 65 6d 61 22 20 66 6c 61 67 2e 20 54 68 69 73 20 ema" flag. This
1bac0 68 61 73 20 74 68 65 20 73 61 6d 65 20 65 66 66 has the same eff
1bad0 65 63 74 20 61 6e 64 20 69 73 20 6c 6f 67 69 63 ect and is logic
1bae0 61 6c 6c 79 20 65 71 75 69 76 61 6c 65 6e 74 0a ally equivalent.
1baf0 2a 2a 20 74 6f 20 73 65 74 74 69 6e 67 20 5b 50 ** to setting [P
1bb00 52 41 47 4d 41 20 77 72 69 74 61 62 6c 65 5f 73 RAGMA writable_s
1bb10 63 68 65 6d 61 3d 4f 4e 5d 20 6f 72 20 5b 50 52 chema=ON] or [PR
1bb20 41 47 4d 41 20 77 72 69 74 61 62 6c 65 5f 73 63 AGMA writable_sc
1bb30 68 65 6d 61 3d 4f 46 46 5d 2e 0a 2a 2a 20 54 68 hema=OFF]..** Th
1bb40 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
1bb50 20 74 6f 20 74 68 69 73 20 73 65 74 74 69 6e 67 to this setting
1bb60 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 is an integer w
1bb70 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 hich is 0 to dis
1bb80 61 62 6c 65 20 0a 2a 2a 20 74 68 65 20 77 72 69 able .** the wri
1bb90 74 61 62 6c 65 5f 73 63 68 65 6d 61 2c 20 70 6f table_schema, po
1bba0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 sitive to enable
1bbb0 20 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61 writable_schema
1bbc0 2c 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f , or negative to
1bbd0 0a 2a 2a 20 6c 65 61 76 65 20 74 68 65 20 73 65 .** leave the se
1bbe0 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e tting unchanged.
1bbf0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
1bc00 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 meter is a point
1bc10 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 74 65 er to an.** inte
1bc20 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 20 69 ger into which i
1bc30 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 s written 0 or 1
1bc40 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 to indicate whe
1bc50 74 68 65 72 20 74 68 65 20 77 72 69 74 61 62 6c ther the writabl
1bc60 65 5f 73 63 68 65 6d 61 0a 2a 2a 20 69 73 20 65 e_schema.** is e
1bc70 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c nabled or disabl
1bc80 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 ed following thi
1bc90 73 20 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e s call..** </dd>
1bca0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
1bcb0 44 42 43 4f 4e 46 49 47 5f 4c 45 47 41 43 59 5f DBCONFIG_LEGACY_
1bcc0 41 4c 54 45 52 5f 54 41 42 4c 45 5d 5d 0a 2a 2a ALTER_TABLE]].**
1bcd0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
1bce0 4e 46 49 47 5f 4c 45 47 41 43 59 5f 41 4c 54 45 NFIG_LEGACY_ALTE
1bcf0 52 5f 54 41 42 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 R_TABLE</dt>.**
1bd00 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 44 <dd>The SQLITE_D
1bd10 42 43 4f 4e 46 49 47 5f 4c 45 47 41 43 59 5f 41 BCONFIG_LEGACY_A
1bd20 4c 54 45 52 5f 54 41 42 4c 45 20 6f 70 74 69 6f LTER_TABLE optio
1bd30 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 n activates or d
1bd40 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 eactivates.** th
1bd50 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f e legacy behavio
1bd60 72 20 6f 66 20 74 68 65 20 5b 41 4c 54 45 52 20 r of the [ALTER
1bd70 54 41 42 4c 45 20 52 45 4e 41 4d 45 5d 20 63 6f TABLE RENAME] co
1bd80 6d 6d 61 6e 64 20 73 75 63 68 20 69 74 0a 2a 2a mmand such it.**
1bd90 20 62 65 68 61 76 65 73 20 61 73 20 69 74 20 64 behaves as it d
1bda0 69 64 20 70 72 69 6f 72 20 74 6f 20 5b 76 65 72 id prior to [ver
1bdb0 73 69 6f 6e 20 33 2e 32 34 2e 30 5d 20 28 32 30 sion 3.24.0] (20
1bdc0 31 38 2d 30 36 2d 30 34 29 2e 20 20 53 65 65 20 18-06-04). See
1bdd0 74 68 65 0a 2a 2a 20 22 43 6f 6d 70 61 74 69 62 the.** "Compatib
1bde0 69 6c 69 74 79 20 4e 6f 74 69 63 65 22 20 6f 6e ility Notice" on
1bdf0 20 74 68 65 20 5b 41 4c 54 45 52 20 54 41 42 4c the [ALTER TABL
1be00 45 20 52 45 4e 41 4d 45 20 64 6f 63 75 6d 65 6e E RENAME documen
1be10 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61 tation] for.** a
1be20 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
1be30 61 74 69 6f 6e 2e 20 54 68 69 73 20 66 65 61 74 ation. This feat
1be40 75 72 65 20 63 61 6e 20 61 6c 73 6f 20 62 65 20 ure can also be
1be50 74 75 72 6e 65 64 20 6f 6e 20 61 6e 64 20 6f 66 turned on and of
1be60 66 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b f.** using the [
1be70 50 52 41 47 4d 41 20 6c 65 67 61 63 79 5f 61 6c PRAGMA legacy_al
1be80 74 65 72 5f 74 61 62 6c 65 5d 20 73 74 61 74 65 ter_table] state
1be90 6d 65 6e 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a ment..** </dd>.*
1bea0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 *.** [[SQLITE_DB
1beb0 43 4f 4e 46 49 47 5f 44 51 53 5f 44 4d 4c 5d 5d CONFIG_DQS_DML]]
1bec0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
1bed0 42 43 4f 4e 46 49 47 5f 44 51 53 5f 44 4d 4c 3c BCONFIG_DQS_DML<
1bee0 2f 74 64 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /td>.** <dd>The
1bef0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
1bf00 44 51 53 5f 44 4d 4c 20 6f 70 74 69 6f 6e 20 61 DQS_DML option a
1bf10 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 ctivates or deac
1bf20 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 6c tivates.** the l
1bf30 65 67 61 63 79 20 5b 64 6f 75 62 6c 65 2d 71 75 egacy [double-qu
1bf40 6f 74 65 64 20 73 74 72 69 6e 67 20 6c 69 74 65 oted string lite
1bf50 72 61 6c 5d 20 6d 69 73 66 65 61 74 75 72 65 20 ral] misfeature
1bf60 66 6f 72 20 44 4d 4c 20 73 74 61 74 65 6d 65 6e for DML statemen
1bf70 74 0a 2a 2a 20 6f 6e 6c 79 2c 20 74 68 61 74 20 t.** only, that
1bf80 69 73 20 44 45 4c 45 54 45 2c 20 49 4e 53 45 52 is DELETE, INSER
1bf90 54 2c 20 53 45 4c 45 43 54 2c 20 61 6e 64 20 55 T, SELECT, and U
1bfa0 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 73 PDATE statements
1bfb0 2e 20 54 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 . The.** default
1bfc0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 73 value of this s
1bfd0 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d etting is determ
1bfe0 69 6e 65 64 20 62 79 20 74 68 65 20 5b 2d 44 53 ined by the [-DS
1bff0 51 4c 49 54 45 5f 44 51 53 5d 0a 2a 2a 20 63 6f QLITE_DQS].** co
1c000 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
1c010 6e 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a n..** </dd>.**.*
1c020 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e * [[SQLITE_DBCON
1c030 46 49 47 5f 44 51 53 5f 44 44 4c 5d 5d 0a 2a 2a FIG_DQS_DDL]].**
1c040 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
1c050 4e 46 49 47 5f 44 51 53 5f 44 44 4c 3c 2f 74 64 NFIG_DQS_DDL</td
1c060 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c >.** <dd>The SQL
1c070 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 51 53 ITE_DBCONFIG_DQS
1c080 20 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65 option activate
1c090 73 20 6f 72 20 64 65 61 63 74 69 76 61 74 65 73 s or deactivates
1c0a0 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20 5b .** the legacy [
1c0b0 64 6f 75 62 6c 65 2d 71 75 6f 74 65 64 20 73 74 double-quoted st
1c0c0 72 69 6e 67 20 6c 69 74 65 72 61 6c 5d 20 6d 69 ring literal] mi
1c0d0 73 66 65 61 74 75 72 65 20 66 6f 72 20 44 44 4c sfeature for DDL
1c0e0 20 73 74 61 74 65 6d 65 6e 74 73 2c 0a 2a 2a 20 statements,.**
1c0f0 73 75 63 68 20 61 73 20 43 52 45 41 54 45 20 54 such as CREATE T
1c100 41 42 4c 45 20 61 6e 64 20 43 52 45 41 54 45 20 ABLE and CREATE
1c110 49 4e 44 45 58 2e 20 54 68 65 0a 2a 2a 20 64 65 INDEX. The.** de
1c120 66 61 75 6c 74 20 76 61 6c 75 65 20 6f 66 20 74 fault value of t
1c130 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 64 his setting is d
1c140 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 etermined by the
1c150 20 5b 2d 44 53 51 4c 49 54 45 5f 44 51 53 5d 0a [-DSQLITE_DQS].
1c160 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 ** compile-time
1c170 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 64 3e option..** </dd>
1c180 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 .** </dl>.*/.#de
1c190 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
1c1a0 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 NFIG_MAINDBNAME
1c1b0 20 20 20 20 20 20 20 20 20 20 20 31 30 30 30 20 1000
1c1c0 2f 2a 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a /* const char* *
1c1d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1c1e0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
1c1f0 49 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20 IDE
1c200 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 1001 /* void* in
1c210 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 t int */.#define
1c220 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
1c230 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 _ENABLE_FKEY
1c240 20 20 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 1002 /* i
1c250 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 nt int* */.#defi
1c260 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
1c270 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 IG_ENABLE_TRIGGE
1c280 52 20 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a R 1003 /*
1c290 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 int int* */.#de
1c2a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
1c2b0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 NFIG_ENABLE_FTS3
1c2c0 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 _TOKENIZER 1004
1c2d0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 /* int int* */.#
1c2e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
1c2f0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f CONFIG_ENABLE_LO
1c300 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 AD_EXTENSION 100
1c310 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 5 /* int int* */
1c320 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1c330 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 DBCONFIG_NO_CKPT
1c340 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20 31 _ON_CLOSE 1
1c350 30 30 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 006 /* int int*
1c360 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1c370 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
1c380 45 5f 51 50 53 47 20 20 20 20 20 20 20 20 20 20 E_QPSG
1c390 20 31 30 30 37 20 2f 2a 20 69 6e 74 20 69 6e 74 1007 /* int int
1c3a0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
1c3b0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49 ITE_DBCONFIG_TRI
1c3c0 47 47 45 52 5f 45 51 50 20 20 20 20 20 20 20 20 GGER_EQP
1c3d0 20 20 20 31 30 30 38 20 2f 2a 20 69 6e 74 20 69 1008 /* int i
1c3e0 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nt* */.#define S
1c3f0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 QLITE_DBCONFIG_R
1c400 45 53 45 54 5f 44 41 54 41 42 41 53 45 20 20 20 ESET_DATABASE
1c410 20 20 20 20 20 31 30 30 39 20 2f 2a 20 69 6e 74 1009 /* int
1c420 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 int* */.#define
1c430 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
1c440 5f 44 45 46 45 4e 53 49 56 45 20 20 20 20 20 20 _DEFENSIVE
1c450 20 20 20 20 20 20 20 31 30 31 30 20 2f 2a 20 69 1010 /* i
1c460 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 nt int* */.#defi
1c470 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
1c480 49 47 5f 57 52 49 54 41 42 4c 45 5f 53 43 48 45 IG_WRITABLE_SCHE
1c490 4d 41 20 20 20 20 20 20 20 31 30 31 31 20 2f 2a MA 1011 /*
1c4a0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 int int* */.#de
1c4b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
1c4c0 4e 46 49 47 5f 4c 45 47 41 43 59 5f 41 4c 54 45 NFIG_LEGACY_ALTE
1c4d0 52 5f 54 41 42 4c 45 20 20 20 20 31 30 31 32 20 R_TABLE 1012
1c4e0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 /* int int* */.#
1c4f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
1c500 43 4f 4e 46 49 47 5f 44 51 53 5f 44 4d 4c 20 20 CONFIG_DQS_DML
1c510 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30 31 101
1c520 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 3 /* int int* */
1c530 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1c540 44 42 43 4f 4e 46 49 47 5f 44 51 53 5f 44 44 4c DBCONFIG_DQS_DDL
1c550 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
1c560 30 31 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 014 /* int int*
1c570 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1c580 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
1c590 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 E_VIEW
1c5a0 20 31 30 31 35 20 2f 2a 20 69 6e 74 20 69 6e 74 1015 /* int int
1c5b0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
1c5c0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 58 ITE_DBCONFIG_MAX
1c5d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1c5e0 20 20 20 31 30 31 35 20 2f 2a 20 4c 61 72 67 65 1015 /* Large
1c5f0 73 74 20 44 42 43 4f 4e 46 49 47 20 2a 2f 0a 0a st DBCONFIG */..
1c600 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1c610 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c Enable Or Disabl
1c620 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c e Extended Resul
1c630 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f t Codes.** METHO
1c640 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
1c650 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
1c660 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
1c670 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e des() routine en
1c680 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 ables or disable
1c690 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 s the.** [extend
1c6a0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d ed result codes]
1c6b0 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 feature of SQLi
1c6c0 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 te. ^The extende
1c6d0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 d result.** code
1c6e0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 s are disabled b
1c6f0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 y default for hi
1c700 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 storical compati
1c710 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 bility..*/.int s
1c720 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
1c730 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c result_codes(sql
1c740 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 ite3*, int onoff
1c750 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1c760 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 EF: Last Insert
1c770 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a Rowid.** METHOD:
1c780 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
1c790 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f Each entry in mo
1c7a0 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 st SQLite tables
1c7b0 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 (except for [WI
1c7c0 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 THOUT ROWID] tab
1c7d0 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e les).** has a un
1c7e0 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e ique 64-bit sign
1c7f0 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 ed.** integer ke
1c800 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f y called the [RO
1c810 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 WID | "rowid"].
1c820 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c ^The rowid is al
1c830 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a ways available.*
1c840 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 * as an undeclar
1c850 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 ed column named
1c860 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f ROWID, OID, or _
1c870 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 ROWID_ as long a
1c880 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 s those.** names
1c890 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 are not also us
1c8a0 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 ed by explicitly
1c8b0 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e declared column
1c8c0 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 s. ^If.** the ta
1c8d0 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e ble has a column
1c8e0 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 of type [INTEGE
1c8f0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 R PRIMARY KEY] t
1c900 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a hen that column.
1c910 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c ** is another al
1c920 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 ias for the rowi
1c930 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
1c940 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
1c950 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 t_rowid(D) inter
1c960 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74 face usually ret
1c970 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d urns the [rowid]
1c980 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 of.** the most
1c990 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 recent successfu
1c9a0 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 l [INSERT] into
1c9b0 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 a rowid table or
1c9c0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d [virtual table]
1c9d0 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 .** on database
1c9e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 connection D. ^I
1c9f0 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 nserts into [WIT
1ca00 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c HOUT ROWID] tabl
1ca10 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 es are not.** re
1ca20 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 corded. ^If no s
1ca30 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
1ca40 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 T]s into rowid t
1ca50 61 62 6c 65 73 20 68 61 76 65 20 65 76 65 72 20 ables have ever
1ca60 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 occurred .** on
1ca70 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
1ca80 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 nection D, then
1ca90 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
1caa0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 ert_rowid(D) ret
1cab0 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a urns .** zero..*
1cac0 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 *.** As well as
1cad0 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 being set automa
1cae0 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 tically as rows
1caf0 61 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 are inserted int
1cb00 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 o database.** ta
1cb10 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 bles, the value
1cb20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 returned by this
1cb30 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 function may be
1cb40 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20 set explicitly
1cb50 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 by.** [sqlite3_s
1cb60 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 et_last_insert_r
1cb70 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f owid()].**.** So
1cb80 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 me virtual table
1cb90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
1cba0 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73 may INSERT rows
1cbb0 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c into rowid tabl
1cbc0 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 es as.** part of
1cbd0 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 committing a tr
1cbe0 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 ansaction (e.g.
1cbf0 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61 63 to flush data ac
1cc00 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d cumulated in mem
1cc10 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e ory.** to disk).
1cc20 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 73 75 In this case su
1cc30 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
1cc40 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 o this function
1cc50 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 return the rowid
1cc60 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
1cc70 69 74 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e ith these intern
1cc80 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 al INSERT operat
1cc90 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64 ions, which lead
1cca0 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 s to .** unintui
1ccb0 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69 tive results. Vi
1ccc0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c rtual table impl
1ccd0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 ementations that
1cce0 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77 do write to row
1ccf0 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 id.** tables in
1cd00 74 68 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f this way can avo
1cd10 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 id this problem
1cd20 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65 by restoring the
1cd30 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f original .** ro
1cd40 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20 wid value using
1cd50 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 [sqlite3_set_las
1cd60 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 t_insert_rowid()
1cd70 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 ] before returni
1cd80 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 ng .** control t
1cd90 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a o the user..**.*
1cda0 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 * ^(If an [INSER
1cdb0 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e T] occurs within
1cdc0 20 61 20 74 72 69 67 67 65 72 20 74 68 65 6e 20 a trigger then
1cdd0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c this routine wil
1cde0 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 l .** return the
1cdf0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 [rowid] of the
1ce00 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73 20 inserted row as
1ce10 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 long as the trig
1ce20 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 ger is .** runni
1ce30 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69 ng. Once the tri
1ce40 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 gger program end
1ce50 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 s, the value ret
1ce60 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 urned .** by thi
1ce70 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 s routine revert
1ce80 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 s to what it was
1ce90 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 before the trig
1cea0 67 65 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e ger was fired.)^
1ceb0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 .**.** ^An [INSE
1cec0 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 RT] that fails d
1ced0 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 ue to a constrai
1cee0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 nt violation is
1cef0 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 not a.** success
1cf00 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 ful [INSERT] and
1cf10 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 does not change
1cf20 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
1cf30 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 ned by this.** r
1cf40 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 outine. ^Thus I
1cf50 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 NSERT OR FAIL, I
1cf60 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c NSERT OR IGNORE,
1cf70 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 INSERT OR ROLLB
1cf80 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 ACK,.** and INSE
1cf90 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 RT OR ABORT make
1cfa0 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 no changes to t
1cfb0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
1cfc0 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 of this.** routi
1cfd0 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e ne when their in
1cfe0 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 sertion fails.
1cff0 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 ^(When INSERT OR
1d000 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f REPLACE.** enco
1d010 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 unters a constra
1d020 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 int violation, i
1d030 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e t does not fail.
1d040 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 The.** INSERT
1d050 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d continues to com
1d060 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 pletion after de
1d070 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 leting rows that
1d080 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 caused.** the c
1d090 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 onstraint proble
1d0a0 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 m so INSERT OR R
1d0b0 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 EPLACE will alwa
1d0c0 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 ys change.** the
1d0d0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
1d0e0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e this interface.
1d0f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 )^.**.** ^For th
1d100 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 e purposes of th
1d110 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b is routine, an [
1d120 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 INSERT] is consi
1d130 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 dered to.** be s
1d140 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 uccessful even i
1d150 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 f it is subseque
1d160 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ntly rolled back
1d170 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e ..**.** This fun
1d180 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 ction is accessi
1d190 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 ble to SQL state
1d1a0 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a ments via the.**
1d1b0 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f [last_insert_ro
1d1c0 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 wid() SQL functi
1d1d0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 on]..**.** If a
1d1e0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 separate thread
1d1f0 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b performs a new [
1d200 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 INSERT] on the s
1d210 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 ame.** database
1d220 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 connection while
1d230 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 the [sqlite3_la
1d240 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
1d250 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 )].** function i
1d260 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 s running and th
1d270 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c us changes the l
1d280 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 ast insert [rowi
1d290 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 d],.** then the
1d2a0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
1d2b0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f y [sqlite3_last_
1d2c0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 insert_rowid()]
1d2d0 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 is.** unpredicta
1d2e0 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f ble and might no
1d2f0 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 t equal either t
1d300 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 he old or the ne
1d310 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 w.** last insert
1d320 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c [rowid]..*/.sql
1d330 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
1d340 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
1d350 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a owid(sqlite3*);.
1d360 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1d370 20 53 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e Set the Last In
1d380 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65 sert Rowid value
1d390 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c ..** METHOD: sql
1d3a0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ite3.**.** The s
1d3b0 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f qlite3_set_last_
1d3c0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 insert_rowid(D,
1d3d0 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 R) method allows
1d3e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
1d3f0 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 to.** set the v
1d400 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
1d410 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 calling sqlite3
1d420 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
1d430 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 id(D) to R .** w
1d440 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 ithout inserting
1d450 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 a row into the
1d460 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 database..*/.voi
1d470 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 d sqlite3_set_la
1d480 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
1d490 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 sqlite3*,sqlite3
1d4a0 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _int64);../*.**
1d4b0 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 CAPI3REF: Count
1d4c0 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f The Number Of Ro
1d4d0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d ws Modified.** M
1d4e0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
1d4f0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 *.** ^This funct
1d500 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 ion returns the
1d510 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d number of rows m
1d520 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 odified, inserte
1d530 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 d or.** deleted
1d540 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 by the most rece
1d550 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 ntly completed I
1d560 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 NSERT, UPDATE or
1d570 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 DELETE.** state
1d580 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 ment on the data
1d590 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1d5a0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
1d5b0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e only parameter.
1d5c0 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 .** ^Executing a
1d5d0 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 ny other type of
1d5e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 SQL statement d
1d5f0 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 oes not modify t
1d600 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 he value.** retu
1d610 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e rned by this fun
1d620 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e ction..**.** ^On
1d630 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 ly changes made
1d640 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 directly by the
1d650 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f INSERT, UPDATE o
1d660 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 r DELETE stateme
1d670 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 nt are.** consid
1d680 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 ered - auxiliary
1d690 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 changes caused
1d6a0 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 by [CREATE TRIGG
1d6b0 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 ER | triggers],
1d6c0 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 .** [foreign key
1d6d0 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 actions] or [RE
1d6e0 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e PLACE] constrain
1d6f0 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 t resolution are
1d700 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a not counted..**
1d710 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 .** Changes to
1d720 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 a view that are
1d730 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 0a intercepted by .
1d740 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 ** [INSTEAD OF t
1d750 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 rigger | INSTEAD
1d760 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 OF triggers] ar
1d770 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e e not counted. ^
1d780 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 The value .** re
1d790 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
1d7a0 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 3_changes() imme
1d7b0 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e diately after an
1d7c0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 INSERT, UPDATE
1d7d0 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 or .** DELETE st
1d7e0 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 atement run on a
1d7f0 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 view is always
1d800 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 zero. Only chang
1d810 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 es made to real
1d820 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 .** tables are c
1d830 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 ounted..**.** Th
1d840 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f ings are more co
1d850 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 mplicated if the
1d860 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
1d870 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a () function is.*
1d880 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 * executed while
1d890 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 a trigger progr
1d8a0 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 am is running. T
1d8b0 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 his may happen i
1d8c0 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d f the.** program
1d8d0 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 uses the [chang
1d8e0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f es() SQL functio
1d8f0 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f n], or if some o
1d900 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a ther callback.**
1d910 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 function invoke
1d920 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 s sqlite3_change
1d930 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 s() directly. Es
1d940 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a sentially:.** .*
1d950 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e * <ul>.** <li>
1d960 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 ^(Before enteri
1d970 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72 6f ng a trigger pro
1d980 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 gram the value r
1d990 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 eturned by.**
1d9a0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 sqlite3_cha
1d9b0 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 nges() function
1d9c0 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 is saved. After
1d9d0 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 the trigger prog
1d9e0 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 ram .** h
1d9f0 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 as finished, the
1da00 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 original value
1da10 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a is restored.)^.*
1da20 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 * .** <li> ^(W
1da30 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 ithin a trigger
1da40 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 program each INS
1da50 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 ERT, UPDATE and
1da60 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 DELETE .**
1da70 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 statement sets
1da80 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
1da90 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
1daa0 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 hanges() .**
1dab0 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 upon complet
1dac0 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f ion as normal. O
1dad0 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 f course, this v
1dae0 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e alue will not in
1daf0 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 clude .**
1db00 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 any changes per
1db10 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 formed by sub-tr
1db20 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 iggers, as the s
1db30 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
1db40 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 .** valu
1db50 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 e will be saved
1db60 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 and restored aft
1db70 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 er each sub-trig
1db80 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a ger has run.)^.*
1db90 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e * </ul>.** .** ^
1dba0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 This means that
1dbb0 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 if the changes()
1dbc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f SQL function (o
1dbd0 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 r similar) is us
1dbe0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 ed.** by the fir
1dbf0 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 st INSERT, UPDAT
1dc00 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 E or DELETE stat
1dc10 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 ement within a t
1dc20 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 rigger, it .** r
1dc30 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 eturns the value
1dc40 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 as set when the
1dc50 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 calling stateme
1dc60 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 nt began executi
1dc70 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 ng..** ^If it is
1dc80 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65 63 used by the sec
1dc90 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e ond or subsequen
1dca0 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 t such statement
1dcb0 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 within a trigge
1dcc0 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 r .** program, t
1dcd0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
1dce0 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e d reflects the n
1dcf0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f umber of rows mo
1dd00 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a dified by the .*
1dd10 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 * previous INSER
1dd20 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c T, UPDATE or DEL
1dd30 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 ETE statement wi
1dd40 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 thin the same tr
1dd50 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 igger..**.** If
1dd60 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
1dd70 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 d makes changes
1dd80 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 on the same data
1dd90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
1dda0 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 ** while [sqlite
1ddb0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 3_changes()] is
1ddc0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 running then the
1ddd0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a value returned.
1dde0 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 ** is unpredicta
1ddf0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e ble and not mean
1de00 69 6e 67 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 ingful..**.** Se
1de10 65 20 61 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e 0a e also:.** <ul>.
1de20 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 73 71 6c ** <li> the [sql
1de30 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
1de40 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a es()] interface.
1de50 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 6f 75 ** <li> the [cou
1de60 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d nt_changes pragm
1de70 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b a].** <li> the [
1de80 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 changes() SQL fu
1de90 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e 20 nction].** <li>
1dea0 74 68 65 20 5b 64 61 74 61 5f 76 65 72 73 69 6f the [data_versio
1deb0 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 2f 75 n pragma].** </u
1dec0 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 l>.*/.int sqlite
1ded0 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 3_changes(sqlite
1dee0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
1def0 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 3REF: Total Numb
1df00 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 er Of Rows Modif
1df10 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ied.** METHOD: s
1df20 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
1df30 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
1df40 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 rns the total nu
1df50 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 mber of rows ins
1df60 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 erted, modified
1df70 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 or.** deleted by
1df80 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b all [INSERT], [
1df90 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 UPDATE] or [DELE
1dfa0 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 TE] statements c
1dfb0 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 ompleted.** sinc
1dfc0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
1dfd0 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 onnection was op
1dfe0 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 ened, including
1dff0 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 those executed a
1e000 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 s.** part of tri
1e010 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e gger programs. ^
1e020 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 Executing any ot
1e030 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 her type of SQL
1e040 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 statement.** doe
1e050 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 s not affect the
1e060 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
1e070 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c by sqlite3_total
1e080 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a _changes()..** .
1e090 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 ** ^Changes made
1e0a0 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 as part of [for
1e0b0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 eign key actions
1e0c0 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 ] are included i
1e0d0 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 n the.** count,
1e0e0 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 but those made a
1e0f0 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 s part of REPLAC
1e100 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 E constraint res
1e110 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e olution are.** n
1e120 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 ot. ^Changes to
1e130 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 a view that are
1e140 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49 intercepted by I
1e150 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 NSTEAD OF trigge
1e160 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 rs .** are not c
1e170 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 ounted..**.** Th
1e180 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c e [sqlite3_total
1e190 5f 63 68 61 6e 67 65 73 28 44 29 5d 20 69 6e 74 _changes(D)] int
1e1a0 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f erface only repo
1e1b0 72 74 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a rts the number.*
1e1c0 2a 20 6f 66 20 72 6f 77 73 20 74 68 61 74 20 63 * of rows that c
1e1d0 68 61 6e 67 65 64 20 64 75 65 20 74 6f 20 53 51 hanged due to SQ
1e1e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 L statement run
1e1f0 61 67 61 69 6e 73 74 20 64 61 74 61 62 61 73 65 against database
1e200 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 .** connection D
1e210 2e 20 20 41 6e 79 20 63 68 61 6e 67 65 73 20 62 . Any changes b
1e220 79 20 6f 74 68 65 72 20 64 61 74 61 62 61 73 65 y other database
1e230 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 72 65 connections are
1e240 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20 54 6f 20 ignored..** To
1e250 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20 61 detect changes a
1e260 67 61 69 6e 73 74 20 61 20 64 61 74 61 62 61 73 gainst a databas
1e270 65 20 66 69 6c 65 20 66 72 6f 6d 20 6f 74 68 65 e file from othe
1e280 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f r database.** co
1e290 6e 6e 65 63 74 69 6f 6e 73 20 75 73 65 20 74 68 nnections use th
1e2a0 65 20 5b 50 52 41 47 4d 41 20 64 61 74 61 5f 76 e [PRAGMA data_v
1e2b0 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20 ersion] command
1e2c0 6f 72 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 or the.** [SQLIT
1e2d0 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 E_FCNTL_DATA_VER
1e2e0 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e 74 SION] [file cont
1e2f0 72 6f 6c 5d 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 rol]..** .** If
1e300 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
1e310 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 d makes changes
1e320 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 on the same data
1e330 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
1e340 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 ** while [sqlite
1e350 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
1e360 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 )] is running th
1e370 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 en the value.**
1e380 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 returned is unpr
1e390 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f edictable and no
1e3a0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2a t meaningful..**
1e3b0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 0a 2a 2a .** See also:.**
1e3c0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 74 68 <ul>.** <li> th
1e3d0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 e [sqlite3_chang
1e3e0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a es()] interface.
1e3f0 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 6f 75 ** <li> the [cou
1e400 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d nt_changes pragm
1e410 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b a].** <li> the [
1e420 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 changes() SQL fu
1e430 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e 20 nction].** <li>
1e440 74 68 65 20 5b 64 61 74 61 5f 76 65 72 73 69 6f the [data_versio
1e450 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 n pragma].** <li
1e460 3e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 > the [SQLITE_FC
1e470 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e NTL_DATA_VERSION
1e480 5d 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 5d ] [file control]
1e490 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 .** </ul>.*/.int
1e4a0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 sqlite3_total_c
1e4b0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 hanges(sqlite3*)
1e4c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1e4d0 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c F: Interrupt A L
1e4e0 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 ong-Running Quer
1e4f0 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c y.** METHOD: sql
1e500 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 ite3.**.** ^This
1e510 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 function causes
1e520 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 any pending dat
1e530 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 abase operation
1e540 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 to abort and.**
1e550 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 return at its ea
1e560 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 rliest opportuni
1e570 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 ty. This routine
1e580 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a is typically.**
1e590 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f called in respo
1e5a0 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 nse to a user ac
1e5b0 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 tion such as pre
1e5c0 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a ssing "Cancel".*
1e5d0 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 * or Ctrl-C wher
1e5e0 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 e the user wants
1e5f0 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 a long query op
1e600 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a eration to halt.
1e610 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a ** immediately..
1e620 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 **.** ^It is saf
1e630 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 e to call this r
1e640 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 outine from a th
1e650 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 read different f
1e660 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 rom the.** threa
1e670 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e d that is curren
1e680 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 tly running the
1e690 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 database operati
1e6a0 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 on. But it.** i
1e6b0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 s not safe to ca
1e6c0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ll this routine
1e6d0 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 with a [database
1e6e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 connection] tha
1e6f0 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f t.** is closed o
1e700 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 r might close be
1e710 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 fore sqlite3_int
1e720 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 errupt() returns
1e730 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 ..**.** ^If an S
1e740 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 QL operation is
1e750 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 very nearly fini
1e760 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 shed at the time
1e770 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 when.** sqlite3
1e780 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 _interrupt() is
1e790 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 called, then it
1e7a0 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 might not have a
1e7b0 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a n opportunity.**
1e7c0 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 to be interrupt
1e7d0 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e ed and might con
1e7e0 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 tinue to complet
1e7f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 ion..**.** ^An S
1e800 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 QL operation tha
1e810 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 t is interrupted
1e820 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
1e830 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e LITE_INTERRUPT].
1e840 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 .** ^If the inte
1e850 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 rrupted SQL oper
1e860 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 ation is an INSE
1e870 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 RT, UPDATE, or D
1e880 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 ELETE.** that is
1e890 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 inside an expli
1e8a0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c cit transaction,
1e8b0 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 then the entire
1e8c0 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 transaction.**
1e8d0 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 will be rolled b
1e8e0 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ack automaticall
1e8f0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 y..**.** ^The sq
1e900 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
1e910 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 D) call is in ef
1e920 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 fect until all c
1e930 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 urrently running
1e940 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
1e950 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 ts on [database
1e960 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f connection] D co
1e970 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 mplete. ^Any ne
1e980 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 w SQL statements
1e990 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 .** that are sta
1e9a0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 rted after the s
1e9b0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1e9c0 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f () call and befo
1e9d0 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 re the .** runni
1e9e0 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 ng statements re
1e9f0 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 aches zero are i
1ea00 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 nterrupted as if
1ea10 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a they had been.*
1ea20 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 * running prior
1ea30 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 to the sqlite3_i
1ea40 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e nterrupt() call.
1ea50 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 ^New SQL state
1ea60 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 ments.** that ar
1ea70 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 e started after
1ea80 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 the running stat
1ea90 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 ement count reac
1eaa0 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 hes zero are.**
1eab0 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 not effected by
1eac0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 the sqlite3_inte
1ead0 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 rrupt()..** ^A c
1eae0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 all to sqlite3_i
1eaf0 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 nterrupt(D) that
1eb00 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 occurs when the
1eb10 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e re are no runnin
1eb20 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 g.** SQL stateme
1eb30 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 nts is a no-op a
1eb40 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 nd has no effect
1eb50 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e on SQL statemen
1eb60 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 ts.** that are s
1eb70 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 tarted after the
1eb80 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
1eb90 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e pt() call return
1eba0 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 s..*/.void sqlit
1ebb0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c e3_interrupt(sql
1ebc0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
1ebd0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 API3REF: Determi
1ebe0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 ne If An SQL Sta
1ebf0 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 tement Is Comple
1ec00 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 te.**.** These r
1ec10 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 outines are usef
1ec20 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e ul during comman
1ec30 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 d-line input to
1ec40 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 determine if the
1ec50 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e .** currently en
1ec60 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 tered text seems
1ec70 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c to form a compl
1ec80 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ete SQL statemen
1ec90 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 t or.** if addit
1eca0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e ional input is n
1ecb0 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e eeded before sen
1ecc0 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e ding the text in
1ecd0 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 to.** SQLite for
1ece0 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 parsing. ^Thes
1ecf0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
1ed00 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 n 1 if the input
1ed10 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 string.** appea
1ed20 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c rs to be a compl
1ed30 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ete SQL statemen
1ed40 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 t. ^A statement
1ed50 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 is judged to be
1ed60 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 .** complete if
1ed70 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 it ends with a s
1ed80 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 emicolon token a
1ed90 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 nd is not a pref
1eda0 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d ix of a.** well-
1edb0 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 formed CREATE TR
1edc0 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e IGGER statement.
1edd0 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 ^Semicolons th
1ede0 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 at are embedded
1edf0 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 within.** string
1ee00 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f literals or quo
1ee10 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e ted identifier n
1ee20 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 ames or comments
1ee30 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 are not.** inde
1ee40 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 pendent tokens (
1ee50 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 they are part of
1ee60 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 the token in wh
1ee70 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 ich they are.**
1ee80 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 embedded) and th
1ee90 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 us do not count
1eea0 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 as a statement t
1eeb0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 erminator. ^Whi
1eec0 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 tespace.** and c
1eed0 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c omments that fol
1eee0 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 low the final se
1eef0 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f micolon are igno
1ef00 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 red..**.** ^Thes
1ef10 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
1ef20 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 n 0 if the state
1ef30 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 ment is incomple
1ef40 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 te. ^If a.** me
1ef50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
1ef60 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 fails, then SQLI
1ef70 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 TE_NOMEM is retu
1ef80 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 rned..**.** ^The
1ef90 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e se routines do n
1efa0 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c ot parse the SQL
1efb0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 statements thus
1efc0 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 .** will not det
1efd0 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c ect syntacticall
1efe0 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e y incorrect SQL.
1eff0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 .**.** ^(If SQLi
1f000 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 te has not been
1f010 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e initialized usin
1f020 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 g [sqlite3_initi
1f030 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a alize()] prior .
1f040 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 ** to invoking s
1f050 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
1f060 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 6() then sqlite3
1f070 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
1f080 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f invoked.** auto
1f090 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c matically by sql
1f0a0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
1f0b0 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 ). If that init
1f0c0 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 ialization fails
1f0d0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 ,.** then the re
1f0e0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 turn value from
1f0f0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
1f100 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 16() will be non
1f110 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c -zero.** regardl
1f120 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
1f130 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 r not the input
1f140 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e SQL is complete.
1f150 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 )^.**.** The inp
1f160 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ut to [sqlite3_c
1f170 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 omplete()] must
1f180 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e be a zero-termin
1f190 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 ated.** UTF-8 st
1f1a0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ring..**.** The
1f1b0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 input to [sqlite
1f1c0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 3_complete16()]
1f1d0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 must be a zero-t
1f1e0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 erminated.** UTF
1f1f0 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 -16 string in na
1f200 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e tive byte order.
1f210 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
1f220 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 complete(const c
1f230 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 har *sql);.int s
1f240 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
1f250 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6(const void *sq
1f260 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
1f270 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 REF: Register A
1f280 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 Callback To Hand
1f290 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 le SQLITE_BUSY E
1f2a0 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 rrors.** KEYWORD
1f2b0 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 S: {busy-handler
1f2c0 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 callback} {busy
1f2d0 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 handler}.** MET
1f2e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
1f2f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1f300 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 busy_handler(D,X
1f310 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 ,P) routine sets
1f320 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
1f330 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d tion X.** that m
1f340 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 ight be invoked
1f350 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 with argument P
1f360 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 whenever.** an a
1f370 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 ttempt is made t
1f380 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62 o access a datab
1f390 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 ase table associ
1f3a0 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 ated with.** [da
1f3b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1f3c0 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 n] D when anothe
1f3d0 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 r thread.** or p
1f3e0 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74 rocess has the t
1f3f0 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 able locked..**
1f400 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 The sqlite3_busy
1f410 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 _handler() inter
1f420 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 face is used to
1f430 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 implement.** [sq
1f440 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
1f450 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d ut()] and [PRAGM
1f460 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e A busy_timeout].
1f470 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 .**.** ^If the b
1f480 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 usy callback is
1f490 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 NULL, then [SQLI
1f4a0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 TE_BUSY].** is r
1f4b0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 eturned immediat
1f4c0 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 ely upon encount
1f4d0 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 ering the lock.
1f4e0 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 ^If the busy ca
1f4f0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 llback.** is not
1f500 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 NULL, then the
1f510 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 callback might b
1f520 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 e invoked with t
1f530 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a wo arguments..**
1f540 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
1f550 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 rgument to the b
1f560 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 usy handler is a
1f570 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 copy of the voi
1f580 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 d* pointer which
1f590 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 .** is the third
1f5a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
1f5b0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
1f5c0 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e r(). ^The secon
1f5d0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
1f5e0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
1f5f0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 r callback is th
1f600 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 e number of time
1f610 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 s that the busy
1f620 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 handler has.** b
1f630 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 een invoked prev
1f640 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 iously for the s
1f650 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e ame locking even
1f660 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 t. ^If the.** b
1f670 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 usy callback ret
1f680 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 urns 0, then no
1f690 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d additional attem
1f6a0 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a pts are made to.
1f6b0 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 ** access the da
1f6c0 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 tabase and [SQLI
1f6d0 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 TE_BUSY] is retu
1f6e0 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 rned.** to the a
1f6f0 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e pplication..** ^
1f700 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
1f710 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
1f720 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 , then another a
1f730 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 ttempt.** is mad
1f740 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 e to access the
1f750 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 database and the
1f760 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a cycle repeats..
1f770 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e **.** The presen
1f780 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e ce of a busy han
1f790 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 dler does not gu
1f7a0 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 arantee that it
1f7b0 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a will be invoked.
1f7c0 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 ** when there is
1f7d0 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e lock contention
1f7e0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 . ^If SQLite det
1f7f0 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 ermines that inv
1f800 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a oking the busy.*
1f810 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 * handler could
1f820 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 result in a dead
1f830 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f lock, it will go
1f840 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 ahead and retur
1f850 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a n [SQLITE_BUSY].
1f860 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 ** to the applic
1f870 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 ation instead of
1f880 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a invoking the .*
1f890 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a * busy handler..
1f8a0 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 ** Consider a sc
1f8b0 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 enario where one
1f8c0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 process is hold
1f8d0 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 ing a read lock
1f8e0 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 that.** it is tr
1f8f0 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 ying to promote
1f900 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f to a reserved lo
1f910 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f ck and.** a seco
1f920 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f nd process is ho
1f930 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 lding a reserved
1f940 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 lock that it is
1f950 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 trying.** to pr
1f960 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c omote to an excl
1f970 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 usive lock. The
1f980 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 first process c
1f990 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a annot proceed.**
1f9a0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 because it is b
1f9b0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 locked by the se
1f9c0 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 cond and the sec
1f9d0 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e ond process cann
1f9e0 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 ot.** proceed be
1f9f0 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 cause it is bloc
1fa00 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 ked by the first
1fa10 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 . If both proce
1fa20 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 sses.** invoke t
1fa30 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 he busy handlers
1fa40 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d , neither will m
1fa50 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 ake any progress
1fa60 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a . Therefore,.**
1fa70 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 SQLite returns
1fa80 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f [SQLITE_BUSY] fo
1fa90 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 r the first proc
1faa0 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 ess, hoping that
1fab0 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e this.** will in
1fac0 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 duce the first p
1fad0 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 rocess to releas
1fae0 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 e its read lock
1faf0 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 and allow.** the
1fb00 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
1fb10 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a to proceed..**.*
1fb20 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 * ^The default b
1fb30 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 usy callback is
1fb40 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 NULL..**.** ^(Th
1fb50 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ere can only be
1fb60 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 a single busy ha
1fb70 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f ndler defined fo
1fb80 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 r each.** [datab
1fb90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
1fba0 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 Setting a new
1fbb0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 busy handler cle
1fbc0 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 ars any.** previ
1fbd0 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 ously set handle
1fbe0 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 r.)^ ^Note that
1fbf0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
1fc00 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 3_busy_timeout()
1fc10 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 ].** or evaluati
1fc20 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f ng [PRAGMA busy_
1fc30 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 timeout=N] will
1fc40 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 change the.** bu
1fc50 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 sy handler and t
1fc60 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 hus clear any pr
1fc70 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 eviously set bus
1fc80 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a y handler..**.**
1fc90 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 The busy callba
1fca0 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 ck should not ta
1fcb0 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 ke any actions w
1fcc0 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a hich modify the.
1fcd0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
1fce0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
1fcf0 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e ked the busy han
1fd00 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 dler. In other
1fd10 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 words,.** the bu
1fd20 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f sy handler is no
1fd30 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e t reentrant. An
1fd40 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a y such actions.*
1fd50 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 * result in unde
1fd60 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a fined behavior..
1fd70 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 ** .** A busy ha
1fd80 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 ndler must not c
1fd90 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 lose the databas
1fda0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
1fdb0 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 or [prepared sta
1fdc0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 tement] that inv
1fdd0 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 oked the busy ha
1fde0 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ndler..*/.int sq
1fdf0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
1fe00 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28 er(sqlite3*,int(
1fe10 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f *)(void*,int),vo
1fe20 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
1fe30 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 I3REF: Set A Bus
1fe40 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 y Timeout.** MET
1fe50 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
1fe60 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
1fe70 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 sets a [sqlite3
1fe80 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 _busy_handler |
1fe90 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 busy handler] th
1fea0 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 at sleeps.** for
1feb0 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f a specified amo
1fec0 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e unt of time when
1fed0 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b a table is lock
1fee0 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 ed. ^The handle
1fef0 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 r.** will sleep
1ff00 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 multiple times u
1ff10 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d ntil at least "m
1ff20 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 s" milliseconds
1ff30 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 of sleeping.** h
1ff40 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e ave accumulated.
1ff50 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 ^After at leas
1ff60 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f t "ms" milliseco
1ff70 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c nds of sleeping,
1ff80 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 .** the handler
1ff90 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 returns 0 which
1ffa0 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f causes [sqlite3_
1ffb0 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 step()] to retur
1ffc0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 n.** [SQLITE_BUS
1ffd0 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 Y]..**.** ^Calli
1ffe0 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ng this routine
1fff0 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 with an argument
20000 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 less than or eq
20010 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 ual to zero.** t
20020 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 urns off all bus
20030 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a y handlers..**.*
20040 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e * ^(There can on
20050 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 ly be a single b
20060 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 usy handler for
20070 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 a particular.**
20080 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
20090 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 tion] at any giv
200a0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 en moment. If a
200b0 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 nother busy hand
200c0 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e ler.** was defin
200d0 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 ed (using [sqli
200e0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
200f0 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 ()]) prior to ca
20100 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f lling.** this ro
20110 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 utine, that othe
20120 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 r busy handler i
20130 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a s cleared.)^.**.
20140 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 ** See also: [P
20150 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f RAGMA busy_timeo
20160 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ut].*/.int sqlit
20170 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
20180 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 sqlite3*, int ms
20190 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
201a0 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 EF: Convenience
201b0 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e Routines For Run
201c0 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 ning Queries.**
201d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
201e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 **.** This is a
201f0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
20200 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 that is preserv
20210 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
20220 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a compatibility..
20230 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 ** Use of this i
20240 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
20250 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a recommended..**.
20260 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 ** Definition: A
20270 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 <b>result table
20280 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 </b> is memory d
20290 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 ata structure cr
202a0 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 eated by the.**
202b0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
202c0 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e le()] interface.
202d0 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 A result table
202e0 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 records the.**
202f0 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 complete query r
20300 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 esults from one
20310 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e or more queries.
20320 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 .**.** The table
20330 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 conceptually ha
20340 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f s a number of ro
20350 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 ws and columns.
20360 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 But.** these nu
20370 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 mbers are not pa
20380 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 rt of the result
20390 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 table itself.
203a0 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 These.** numbers
203b0 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 are obtained se
203c0 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e parately. Let N
203d0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f be the number o
203e0 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 f rows.** and M
203f0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 be the number of
20400 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 columns..**.**
20410 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 A result table i
20420 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
20430 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 inters to zero-t
20440 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
20450 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 strings..** Ther
20460 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c e are (N+1)*M el
20470 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 ements in the ar
20480 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 ray. The first
20490 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 M pointers point
204a0 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d .** to zero-term
204b0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 inated strings t
204c0 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 hat contain the
204d0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f names of the co
204e0 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 lumns..** The re
204f0 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 maining entries
20500 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 all point to que
20510 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c ry results. NUL
20520 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a L values result.
20530 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 ** in NULL point
20540 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 ers. All other
20550 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 values are in th
20560 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 eir UTF-8 zero-t
20570 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 erminated.** str
20580 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 ing representati
20590 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 on as returned b
205a0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d y [sqlite3_colum
205b0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a n_text()]..**.**
205c0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
205d0 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 might consist of
205e0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d one or more mem
205f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e ory allocations.
20600 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 .** It is not sa
20610 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 fe to pass a res
20620 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 ult table direct
20630 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 ly to [sqlite3_f
20640 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 ree()]..** A res
20650 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 ult table should
20660 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
20670 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
20680 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a ree_table()]..**
20690 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d .** ^(As an exam
206a0 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ple of the resul
206b0 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 t table format,
206c0 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 suppose a query
206d0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 result.** is as
206e0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
206f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
20700 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 .** Name
20710 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 | Age.**
20720 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d ---------
20730 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a --------------.*
20740 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 * Alice
20750 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 | 43.**
20760 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 Bob
20770 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 | 28.** C
20780 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a indy | 21.
20790 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
207a0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
207b0 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d re are two colum
207c0 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 n (M==2) and thr
207d0 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 ee rows (N==3).
207e0 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 Thus the.** res
207f0 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 ult table has 8
20800 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 entries. Suppos
20810 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 e the result tab
20820 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 le is stored.**
20830 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 in an array name
20840 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 s azResult. The
20850 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 n azResult holds
20860 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a this content:.*
20870 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
20880 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 ><pre>.**
20890 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d azResult[0]
208a0 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 = "Name";.**
208b0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
208c0 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 1;1] = "Age";.**
208d0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
208e0 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 [2] = "Alice
208f0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
20900 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 esult[3] = "
20910 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 43";.** a
20920 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d zResult[4] =
20930 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 "Bob";.**
20940 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 azResult[5
20950 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 ] = "28";.**
20960 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
20970 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a ;6] = "Cindy";.*
20980 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
20990 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b t[7] = "21";
209a0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
209b0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 kquote>)^.**.**
209c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 ^The sqlite3_get
209d0 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f _table() functio
209e0 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 n evaluates one
209f0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 or more.** semic
20a00 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 olon-separated S
20a10 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e QL statements in
20a20 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
20a30 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 ated UTF-8.** st
20a40 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 ring of its 2nd
20a50 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 parameter and re
20a60 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 turns a result t
20a70 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 able to the.** p
20a80 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 ointer given in
20a90 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 its 3rd paramete
20aa0 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 r..**.** After t
20ab0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 he application h
20ac0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
20ad0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
20ae0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
20af0 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 le(),.** it must
20b00 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 pass the result
20b10 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 table pointer t
20b20 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 o sqlite3_free_t
20b30 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 able() in order
20b40 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 to.** release th
20b50 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 e memory that wa
20b60 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 s malloced. Bec
20b70 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 ause of the way
20b80 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
20b90 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e malloc()] happen
20ba0 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 s within sqlite3
20bb0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 _get_table(), th
20bc0 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e e calling.** fun
20bd0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 ction must not t
20be0 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 ry to call [sqli
20bf0 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 te3_free()] dire
20c00 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b ctly. Only.** [
20c10 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
20c20 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f le()] is able to
20c30 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d release the mem
20c40 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 ory properly and
20c50 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 safely..**.** T
20c60 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
20c70 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 able() interface
20c80 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 is implemented
20c90 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f as a wrapper aro
20ca0 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f und.** [sqlite3_
20cb0 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 exec()]. The sq
20cc0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
20cd0 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e ) routine does n
20ce0 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a ot have access.*
20cf0 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 * to any interna
20d00 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 l data structure
20d10 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 s of SQLite. It
20d20 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 uses only the p
20d30 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 ublic.** interfa
20d40 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e ce defined here.
20d50 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e As a consequen
20d60 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 ce, errors that
20d70 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 occur in the.**
20d80 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 wrapper layer ou
20d90 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 tside of the int
20da0 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 ernal [sqlite3_e
20db0 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 xec()] call are
20dc0 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 not.** reflected
20dd0 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 in subsequent c
20de0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
20df0 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a _errcode()] or.*
20e00 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 * [sqlite3_errms
20e10 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c g()]..*/.int sql
20e20 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a ite3_get_table(.
20e30 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
20e40 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 /* An op
20e50 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 en database */.
20e60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
20e70 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f l, /* SQL to
20e80 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
20e90 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 . char ***pazRe
20ea0 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 sult, /* Resu
20eb0 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 lts of the query
20ec0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 */. int *pnRow
20ed0 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e , /* N
20ee0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 umber of result
20ef0 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 rows written her
20f00 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f e */. int *pnCo
20f10 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 lumn, /*
20f20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 Number of result
20f30 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e columns written
20f40 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 here */. char
20f50 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 **pzErrmsg
20f60 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 /* Error msg wr
20f70 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b itten here */.);
20f80 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 .void sqlite3_fr
20f90 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a ee_table(char **
20fa0 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 result);../*.**
20fb0 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 CAPI3REF: Format
20fc0 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 ted String Print
20fd0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a ing Functions.**
20fe0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
20ff0 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b es are work-alik
21000 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 es of the "print
21010 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 f()" family of f
21020 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d unctions.** from
21030 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 the standard C
21040 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 library..** Thes
21050 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 e routines under
21060 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 stand most of th
21070 65 20 63 6f 6d 6d 6f 6e 20 66 6f 72 6d 61 74 74 e common formatt
21080 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d ing options from
21090 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 .** the standard
210a0 20 6c 69 62 72 61 72 79 20 70 72 69 6e 74 66 28 library printf(
210b0 29 20 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 ) .** plus some
210c0 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 additional non-s
210d0 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 20 tandard formats
210e0 28 5b 25 71 5d 2c 20 5b 25 51 5d 2c 20 5b 25 77 ([%q], [%Q], [%w
210f0 5d 2c 20 61 6e 64 20 5b 25 7a 5d 29 2e 0a 2a 2a ], and [%z])..**
21100 20 53 65 65 20 74 68 65 20 5b 62 75 69 6c 74 2d See the [built-
21110 69 6e 20 70 72 69 6e 74 66 28 29 5d 20 64 6f 63 in printf()] doc
21120 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 64 umentation for d
21130 65 74 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 etails..**.** ^T
21140 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e he sqlite3_mprin
21150 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 tf() and sqlite3
21160 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 _vmprintf() rout
21170 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 ines write their
21180 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f .** results into
21190 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
211a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
211b0 61 6c 6c 6f 63 36 34 28 29 5d 2e 0a 2a 2a 20 54 alloc64()]..** T
211c0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 he strings retur
211d0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f ned by these two
211e0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 routines should
211f0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 be.** released
21200 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 by [sqlite3_free
21210 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 ()]. ^Both rout
21220 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a ines return a.**
21230 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 NULL pointer if
21240 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
21250 36 34 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 64()] is unable
21260 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 to allocate enou
21270 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 gh.** memory to
21280 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 hold the resulti
21290 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a ng string..**.**
212a0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 ^(The sqlite3_s
212b0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e nprintf() routin
212c0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 e is similar to
212d0 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f "snprintf()" fro
212e0 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 m.** the standar
212f0 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 d C library. Th
21300 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 e result is writ
21310 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 ten into the.**
21320 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 buffer supplied
21330 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
21340 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 rameter whose si
21350 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a ze is given by.*
21360 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 * the first para
21370 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 meter. Note that
21380 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 the order of th
21390 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 e.** first two p
213a0 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 arameters is rev
213b0 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 ersed from snpri
213c0 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 ntf().)^ This i
213d0 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 s an.** historic
213e0 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 al accident that
213f0 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 cannot be fixed
21400 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e without breakin
21410 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 g.** backwards c
21420 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e ompatibility. ^
21430 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 (Note also that
21440 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
21450 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 ().** returns a
21460 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 pointer to its b
21470 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 uffer instead of
21480 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
21490 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 * characters act
214a0 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e ually written in
214b0 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e to the buffer.)^
214c0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a We admit that.
214d0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
214e0 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 characters writ
214f0 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d ten would be a m
21500 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 ore useful retur
21510 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 n.** value but w
21520 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 e cannot change
21530 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
21540 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e on of sqlite3_sn
21550 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 printf().** now
21560 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 without breaking
21570 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a compatibility..
21580 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 **.** ^As long a
21590 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a s the buffer siz
215a0 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 e is greater tha
215b0 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f n zero, sqlite3_
215c0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 snprintf().** gu
215d0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 arantees that th
215e0 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 e buffer is alwa
215f0 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 ys zero-terminat
21600 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a ed. ^The first.
21610 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 ** parameter "n"
21620 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 is the total si
21630 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 ze of the buffer
21640 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 , including spac
21650 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 e for.** the zer
21660 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 o terminator. S
21670 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 o the longest st
21680 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 ring that can be
21690 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 completely.** w
216a0 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e ritten will be n
216b0 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a -1 characters..*
216c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
216d0 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 3_vsnprintf() ro
216e0 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 utine is a varar
216f0 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 gs version of sq
21700 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
21710 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
21720 3a 20 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69 : [built-in pri
21730 6e 74 66 28 29 5d 2c 20 5b 70 72 69 6e 74 66 28 ntf()], [printf(
21740 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a ) SQL function].
21750 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 */.char *sqlite3
21760 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 _mprintf(const c
21770 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 har*,...);.char
21780 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 *sqlite3_vmprint
21790 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 f(const char*, v
217a0 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 a_list);.char *s
217b0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
217c0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 int,char*,const
217d0 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 char*, ...);.cha
217e0 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 r *sqlite3_vsnpr
217f0 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 intf(int,char*,c
21800 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c onst char*, va_l
21810 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ist);../*.** CAP
21820 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c I3REF: Memory Al
21830 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 location Subsyst
21840 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c em.**.** The SQL
21850 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 ite core uses th
21860 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e ese three routin
21870 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 es for all of it
21880 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 s own.** interna
21890 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
218a0 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 ion needs. "Core
218b0 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 " in the previou
218c0 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f s sentence.** do
218d0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f es not include o
218e0 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 perating-system
218f0 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 specific VFS imp
21900 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 lementation. Th
21910 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 e.** Windows VFS
21920 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c uses native mal
21930 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 loc() and free()
21940 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 for some operat
21950 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ions..**.** ^The
21960 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
21970 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
21980 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
21990 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d block.** of mem
219a0 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 ory at least N b
219b0 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 ytes in length,
219c0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 where N is the p
219d0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 arameter..** ^If
219e0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
219f0 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f ) is unable to o
21a00 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 btain sufficient
21a10 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c free.** memory,
21a20 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 it returns a NU
21a30 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 LL pointer. ^If
21a40 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e the parameter N
21a50 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d to.** sqlite3_m
21a60 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 alloc() is zero
21a70 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e or negative then
21a80 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
21a90 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e ) returns.** a N
21aa0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
21ab0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
21ac0 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 malloc64(N) rout
21ad0 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c ine works just l
21ae0 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d ike.** sqlite3_m
21af0 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20 alloc(N) except
21b00 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 that N is an uns
21b10 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74 igned 64-bit int
21b20 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 eger instead.**
21b30 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62 of a signed 32-b
21b40 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a it integer..**.*
21b50 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 * ^Calling sqlit
21b60 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 e3_free() with a
21b70 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 pointer previou
21b80 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 sly returned.**
21b90 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f by sqlite3_mallo
21ba0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 c() or sqlite3_r
21bb0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 ealloc() release
21bc0 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f s that memory so
21bd0 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 .** that it migh
21be0 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 t be reused. ^T
21bf0 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 he sqlite3_free(
21c00 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 ) routine is.**
21c10 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 a no-op if is ca
21c20 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c lled with a NULL
21c30 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 pointer. Passi
21c40 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ng a NULL pointe
21c50 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f r.** to sqlite3_
21c60 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 free() is harmle
21c70 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 ss. After being
21c80 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a freed, memory.*
21c90 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 * should neither
21ca0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 be read nor wri
21cb0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 tten. Even read
21cc0 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 ing previously f
21cd0 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d reed.** memory m
21ce0 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 ight result in a
21cf0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 segmentation fa
21d00 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 ult or other sev
21d10 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 ere error..** Me
21d20 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c mory corruption,
21d30 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 a segmentation
21d40 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 fault, or other
21d50 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 severe error.**
21d60 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 might result if
21d70 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 sqlite3_free() i
21d80 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 s called with a
21d90 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
21da0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 that.** was not
21db0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 obtained from s
21dc0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
21dd0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c or sqlite3_reall
21de0 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 oc()..**.** ^The
21df0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
21e00 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 (X,N) interface
21e10 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 attempts to resi
21e20 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 ze a.** prior me
21e30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
21e40 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 X to be at least
21e50 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 N bytes..** ^If
21e60 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 the X parameter
21e70 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c to sqlite3_real
21e80 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 loc(X,N).** is a
21e90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
21ea0 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 en its behavior
21eb0 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 is identical to
21ec0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 calling.** sqlit
21ed0 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a e3_malloc(N)..**
21ee0 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d ^If the N param
21ef0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
21f00 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 realloc(X,N) is
21f10 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 zero or.** negat
21f20 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 ive then the beh
21f30 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 avior is exactly
21f40 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c the same as cal
21f50 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ling.** sqlite3_
21f60 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c free(X)..** ^sql
21f70 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e ite3_realloc(X,N
21f80 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e ) returns a poin
21f90 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 ter to a memory
21fa0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 allocation.** of
21fb0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 at least N byte
21fc0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c s in size or NUL
21fd0 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e L if insufficien
21fe0 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69 t memory is avai
21ff0 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 lable..** ^If M
22000 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 is the size of t
22010 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
22020 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c ion, then min(N,
22030 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 M) bytes.** of t
22040 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
22050 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 ion are copied i
22060 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e nto the beginnin
22070 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 g of buffer retu
22080 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 rned.** by sqlit
22090 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 e3_realloc(X,N)
220a0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c and the prior al
220b0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 location is free
220c0 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 d..** ^If sqlite
220d0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 3_realloc(X,N) r
220e0 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 eturns NULL and
220f0 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 N is positive, t
22100 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 hen the.** prior
22110 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e allocation is n
22120 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 ot freed..**.**
22130 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 ^The sqlite3_rea
22140 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 lloc64(X,N) inte
22150 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65 rfaces works the
22160 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 same as.** sqli
22170 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
22180 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 except that N i
22190 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 s a 64-bit unsig
221a0 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74 ned integer inst
221b0 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 ead.** of a 32-b
221c0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
221d0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 r..**.** ^If X i
221e0 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 s a memory alloc
221f0 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 ation previously
22200 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 obtained from s
22210 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c qlite3_malloc(),
22220 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c .** sqlite3_mall
22230 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f oc64(), sqlite3_
22240 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 realloc(), or sq
22250 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 lite3_realloc64(
22260 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 ), then.** sqlit
22270 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 e3_msize(X) retu
22280 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 rns the size of
22290 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f that memory allo
222a0 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e cation in bytes.
222b0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 .** ^The value r
222c0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
222d0 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 e3_msize(X) migh
222e0 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e t be larger than
222f0 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f the number.** o
22300 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65 f bytes requeste
22310 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c d when X was all
22320 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69 ocated. ^If X i
22330 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
22340 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 then.** sqlite3
22350 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e _msize(X) return
22360 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f s zero. If X po
22370 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e ints to somethin
22380 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a g that is not.**
22390 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f the beginning o
223a0 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 f memory allocat
223b0 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f ion, or if it po
223c0 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 ints to a former
223d0 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f ly.** valid memo
223e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 ry allocation th
223f0 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 at has now been
22400 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20 freed, then the
22410 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 behavior.** of s
22420 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 qlite3_msize(X)
22430 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 is undefined and
22440 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75 possibly harmfu
22450 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 l..**.** ^The me
22460 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 mory returned by
22470 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
22480 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c ), sqlite3_reall
22490 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 oc(),.** sqlite3
224a0 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 _malloc64(), and
224b0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
224c0 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 64().** is alway
224d0 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 s aligned to at
224e0 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 least an 8 byte
224f0 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 boundary, or to
22500 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e a.** 4 byte boun
22510 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c dary if the [SQL
22520 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e ITE_4_BYTE_ALIGN
22530 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 ED_MALLOC] compi
22540 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f le-time.** optio
22550 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a n is used..**.**
22560 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 In SQLite versi
22570 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 on 3.5.0 and 3.5
22580 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 .1, it was possi
22590 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a ble to define.**
225a0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 the SQLITE_OMIT
225b0 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 _MEMORY_ALLOCATI
225c0 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 ON which would c
225d0 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 ause the built-i
225e0 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 n.** implementat
225f0 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 ion of these rou
22600 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 tines to be omit
22610 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 ted. That capab
22620 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c ility.** is no l
22630 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 onger provided.
22640 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d Only built-in m
22650 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 emory allocators
22660 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a can be used..**
22670 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c .** Prior to SQL
22680 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e ite version 3.7.
22690 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 10, the Windows
226a0 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 OS interface lay
226b0 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 er called.** the
226c0 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 system malloc()
226d0 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 and free() dire
226e0 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 ctly when conver
226f0 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 ting.** filename
22700 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 s between the UT
22710 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 F-8 encoding use
22720 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 d by SQLite.** a
22730 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 nd whatever file
22740 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 name encoding is
22750 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 used by the par
22760 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a ticular Windows.
22770 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e ** installation.
22780 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 Memory allocat
22790 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 ion errors were
227a0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a detected, but.**
227b0 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 they were repor
227c0 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c ted back as [SQL
227d0 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 ITE_CANTOPEN] or
227e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 .** [SQLITE_IOER
227f0 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b R] rather than [
22800 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a SQLITE_NOMEM]..*
22810 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 *.** The pointer
22820 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 arguments to [s
22830 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 qlite3_free()] a
22840 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c nd [sqlite3_real
22850 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 loc()].** must b
22860 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 e either NULL or
22870 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f else pointers o
22880 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 btained from a p
22890 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 rior.** invocati
228a0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d on of [sqlite3_m
228b0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c alloc()] or [sql
228c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 ite3_realloc()]
228d0 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 that have.** not
228e0 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 yet been releas
228f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 ed..**.** The ap
22900 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e plication must n
22910 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 ot read or write
22920 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 any part of.**
22930 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 a block of memor
22940 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 y after it has b
22950 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 een released usi
22960 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 ng.** [sqlite3_f
22970 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 ree()] or [sqlit
22980 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a e3_realloc()]..*
22990 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f /.void *sqlite3_
229a0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 malloc(int);.voi
229b0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f d *sqlite3_mallo
229c0 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 c64(sqlite3_uint
229d0 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 64);.void *sqlit
229e0 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a e3_realloc(void*
229f0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 , int);.void *sq
22a00 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 lite3_realloc64(
22a10 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 void*, sqlite3_u
22a20 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c int64);.void sql
22a30 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 ite3_free(void*)
22a40 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 ;.sqlite3_uint64
22a50 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 sqlite3_msize(v
22a60 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
22a70 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
22a80 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 llocator Statist
22a90 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ics.**.** SQLite
22aa0 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 provides these
22ab0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 two interfaces f
22ac0 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 or reporting on
22ad0 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 the status.** of
22ae0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 the [sqlite3_ma
22af0 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 lloc()], [sqlite
22b00 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 3_free()], and [
22b10 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
22b20 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 )].** routines,
22b30 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 which form the b
22b40 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
22b50 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
22b60 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 tem..**.** ^The
22b70 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
22b80 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 used()] routine
22b90 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
22ba0 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f er of bytes.** o
22bb0 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 f memory current
22bc0 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 ly outstanding (
22bd0 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 malloced but not
22be0 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 freed)..** ^The
22bf0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
22c00 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f _highwater()] ro
22c10 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
22c20 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c e maximum.** val
22c30 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d ue of [sqlite3_m
22c40 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 emory_used()] si
22c50 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 nce the high-wat
22c60 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c er mark.** was l
22c70 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 ast reset. ^The
22c80 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 values returned
22c90 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d by [sqlite3_mem
22ca0 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a ory_used()] and.
22cb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f ** [sqlite3_memo
22cc0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 ry_highwater()]
22cd0 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 include any over
22ce0 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 head.** added by
22cf0 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 SQLite in its i
22d00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
22d10 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
22d20 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 ()],.** but not
22d30 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 overhead added b
22d40 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c y the any underl
22d50 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 ying system libr
22d60 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ary.** routines
22d70 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 that [sqlite3_ma
22d80 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c lloc()] may call
22d90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d ..**.** ^The mem
22da0 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d ory high-water m
22db0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 ark is reset to
22dc0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 the current valu
22dd0 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 e of.** [sqlite3
22de0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 _memory_used()]
22df0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 if and only if t
22e00 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a he parameter to.
22e10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f ** [sqlite3_memo
22e20 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 ry_highwater()]
22e30 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 is true. ^The v
22e40 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a alue returned.**
22e50 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d by [sqlite3_mem
22e60 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 ory_highwater(1)
22e70 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 ] is the high-wa
22e80 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f ter mark.** prio
22e90 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a r to the reset..
22ea0 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 */.sqlite3_int64
22eb0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f sqlite3_memory_
22ec0 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 used(void);.sqli
22ed0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
22ee0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
22ef0 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 er(int resetFlag
22f00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
22f10 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f EF: Pseudo-Rando
22f20 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 m Number Generat
22f30 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 or.**.** SQLite
22f40 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d contains a high-
22f50 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 quality pseudo-r
22f60 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e andom number gen
22f70 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 erator (PRNG) us
22f80 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 ed to.** select
22f90 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 random [ROWID |
22fa0 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 ROWIDs] when ins
22fb0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 erting new recor
22fc0 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 ds into a table
22fd0 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 that.** already
22fe0 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 uses the largest
22ff0 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 possible [ROWID
23000 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 ]. The PRNG is
23010 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a also used for.**
23020 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 the build-in ra
23030 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f ndom() and rando
23040 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 mblob() SQL func
23050 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 tions. This int
23060 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a erface allows.**
23070 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f applications to
23080 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 access the same
23090 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 PRNG for other
230a0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 purposes..**.**
230b0 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 ^A call to this
230c0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e routine stores N
230d0 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d bytes of random
230e0 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 ness into buffer
230f0 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61 P..** ^The P pa
23100 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61 rameter can be a
23110 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
23120 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f *.** ^If this ro
23130 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 utine has not be
23140 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61 en previously ca
23150 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70 lled or if the p
23160 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 revious.** call
23170 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 had N less than
23180 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f one or a NULL po
23190 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65 inter for P, the
231a0 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a n the PRNG is.**
231b0 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 seeded using ra
231c0 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 ndomness obtaine
231d0 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 d from the xRand
231e0 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 omness method of
231f0 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 .** the default
23200 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
23210 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ject..** ^If the
23220 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 previous call t
23230 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 o this routine h
23240 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 ad an N of 1 or
23250 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f more and a.** no
23260 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68 n-NULL P then th
23270 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e e pseudo-randomn
23280 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 ess is generated
23290 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 .** internally a
232a0 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 nd without recou
232b0 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 rse to the [sqli
232c0 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d te3_vfs] xRandom
232d0 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a ness.** method..
232e0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f */.void sqlite3_
232f0 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e randomness(int N
23300 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a , void *P);../*.
23310 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
23320 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 pile-Time Author
23330 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b ization Callback
23340 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
23350 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ite3.** KEYWORDS
23360 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72 20 63 61 : {authorizer ca
23370 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e 54 llback}.**.** ^T
23380 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 his routine regi
23390 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 sters an authori
233a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 zer callback wit
233b0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a h a particular.*
233c0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
233d0 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 ection], supplie
233e0 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 d in the first a
233f0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 rgument..** ^The
23400 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
23410 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
23420 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 as SQL statement
23430 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 s are being comp
23440 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 iled.** by [sqli
23450 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
23460 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b r its variants [
23470 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
23480 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 v2()],.** [sqlit
23490 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d e3_prepare_v3()]
234a0 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 , [sqlite3_prepa
234b0 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 re16()], [sqlite
234c0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
234d0 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 ],.** and [sqlit
234e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 e3_prepare16_v3(
234f0 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 )]. ^At various
23500 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e .** points durin
23510 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f g the compilatio
23520 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f n process, as lo
23530 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 gic is being cre
23540 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f ated.** to perfo
23550 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f rm various actio
23560 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a ns, the authoriz
23570 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
23580 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 nvoked to.** see
23590 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e if those action
235a0 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 s are allowed.
235b0 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 ^The authorizer
235c0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a callback should.
235d0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ** return [SQLIT
235e0 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 E_OK] to allow t
235f0 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 he action, [SQLI
23600 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 TE_IGNORE] to di
23610 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 sallow the.** sp
23620 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 ecific action bu
23630 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 t allow the SQL
23640 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e statement to con
23650 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 tinue to be.** c
23660 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c ompiled, or [SQL
23670 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 ITE_DENY] to cau
23680 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 se the entire SQ
23690 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 L statement to b
236a0 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 e.** rejected wi
236b0 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 th an error. ^I
236c0 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 f the authorizer
236d0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
236e0 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f s.** any value o
236f0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
23700 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 E_IGNORE], [SQLI
23710 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 TE_OK], or [SQLI
23720 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e TE_DENY].** then
23730 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 the [sqlite3_pr
23740 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 epare_v2()] or e
23750 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 quivalent call t
23760 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a hat triggered.**
23770 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
23780 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 will fail with a
23790 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e n error message.
237a0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
237b0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
237c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 [SQLITE_OK], th
237d0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 at means the ope
237e0 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 ration.** reques
237f0 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 ted is ok. ^Whe
23800 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 n the callback r
23810 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 eturns [SQLITE_D
23820 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 ENY], the.** [sq
23830 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
23840 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e ()] or equivalen
23850 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 t call that trig
23860 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 gered the.** aut
23870 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 horizer will fai
23880 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 l with an error
23890 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 message explaini
238a0 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 ng that.** acces
238b0 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a s is denied. .**
238c0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 .** ^The first p
238d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
238e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
238f0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ack is a copy of
23900 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 the third.** pa
23910 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
23920 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
23930 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 rizer() interfac
23940 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 e. ^The second p
23950 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 arameter.** to t
23960 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 he callback is a
23970 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 n integer [SQLIT
23980 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 E_COPY | action
23990 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 code] that speci
239a0 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 fies.** the part
239b0 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f icular action to
239c0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 be authorized.
239d0 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 ^The third throu
239e0 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 gh sixth paramet
239f0 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 ers.** to the ca
23a00 6c 6c 62 61 63 6b 20 61 72 65 20 65 69 74 68 65 llback are eithe
23a10 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 r NULL pointers
23a20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 or zero-terminat
23a30 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 74 68 ed strings.** th
23a40 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 at contain addit
23a50 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62 ional details ab
23a60 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 out the action t
23a70 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e o be authorized.
23a80 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 .** Applications
23a90 20 6d 75 73 74 20 61 6c 77 61 79 73 20 62 65 20 must always be
23aa0 70 72 65 70 61 72 65 64 20 74 6f 20 65 6e 63 6f prepared to enco
23ab0 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 unter a NULL poi
23ac0 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a 2a 20 6f nter in any.** o
23ad0 66 20 74 68 65 20 74 68 69 72 64 20 74 68 72 6f f the third thro
23ae0 75 67 68 20 74 68 65 20 73 69 78 74 68 20 70 61 ugh the sixth pa
23af0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 rameters of the
23b00 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 authorization ca
23b10 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 49 llback..**.** ^I
23b20 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 f the action cod
23b30 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 e is [SQLITE_REA
23b40 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 D].** and the ca
23b50 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
23b60 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 SQLITE_IGNORE] t
23b70 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 hen the.** [prep
23b80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
23b90 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e statement is con
23ba0 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 structed to subs
23bb0 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c titute.** a NULL
23bc0 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 value in place
23bd0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c of the table col
23be0 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 umn that would h
23bf0 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 ave.** been read
23c00 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 if [SQLITE_OK]
23c10 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 had been returne
23c20 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f d. The [SQLITE_
23c30 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 IGNORE].** retur
23c40 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
23c50 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 deny an untrust
23c60 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 ed user access t
23c70 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 o individual.**
23c80 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 columns of a tab
23c90 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 74 le..** ^When a t
23ca0 61 62 6c 65 20 69 73 20 72 65 66 65 72 65 6e 63 able is referenc
23cb0 65 64 20 62 79 20 61 20 5b 53 45 4c 45 43 54 5d ed by a [SELECT]
23cc0 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d 6e 20 76 but no column v
23cd0 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20 65 78 74 alues are.** ext
23ce0 72 61 63 74 65 64 20 66 72 6f 6d 20 74 68 61 74 racted from that
23cf0 20 74 61 62 6c 65 20 28 66 6f 72 20 65 78 61 6d table (for exam
23d00 70 6c 65 20 69 6e 20 61 20 71 75 65 72 79 20 6c ple in a query l
23d10 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43 54 20 63 ike.** "SELECT c
23d20 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20 74 61 62 ount(*) FROM tab
23d30 22 29 20 74 68 65 6e 20 74 68 65 20 5b 53 51 4c ") then the [SQL
23d40 49 54 45 5f 52 45 41 44 5d 20 61 75 74 68 6f 72 ITE_READ] author
23d50 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a izer callback.**
23d60 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 is invoked once
23d70 20 66 6f 72 20 74 68 61 74 20 74 61 62 6c 65 20 for that table
23d80 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e 20 6e 61 with a column na
23d90 6d 65 20 74 68 61 74 20 69 73 20 61 6e 20 65 6d me that is an em
23da0 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e pty string..** ^
23db0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f If the action co
23dc0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 de is [SQLITE_DE
23dd0 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 LETE] and the ca
23de0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a llback returns.*
23df0 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 * [SQLITE_IGNORE
23e00 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 ] then the [DELE
23e10 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 TE] operation pr
23e20 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a oceeds but the.*
23e30 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 * [truncate opti
23e40 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 mization] is dis
23e50 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f abled and all ro
23e60 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 ws are deleted i
23e70 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a ndividually..**.
23e80 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 ** An authorizer
23e90 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 is used when [s
23ea0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c qlite3_prepare |
23eb0 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 preparing].** S
23ec0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 QL statements fr
23ed0 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 om an untrusted
23ee0 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 source, to ensur
23ef0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 e that the SQL s
23f00 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 tatements.** do
23f10 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 not try to acces
23f20 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 s data they are
23f30 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 not allowed to s
23f40 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 ee, or that they
23f50 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 do not.** try t
23f60 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 o execute malici
23f70 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 ous statements t
23f80 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 hat damage the d
23f90 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a atabase. For.**
23fa0 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 example, an app
23fb0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c lication may all
23fc0 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 ow a user to ent
23fd0 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 er arbitrary.**
23fe0 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 SQL queries for
23ff0 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 evaluation by a
24000 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 database. But t
24010 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
24020 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 oes.** not want
24030 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 the user to be a
24040 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 ble to make arbi
24050 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f trary changes to
24060 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
24070 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 . An authorizer
24080 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 could then be p
24090 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c ut in place whil
240a0 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e e the.** user-en
240b0 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 tered SQL is bei
240c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
240d0 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 are | prepared]
240e0 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 that.** disallow
240f0 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 s everything exc
24100 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 ept [SELECT] sta
24110 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 tements..**.** A
24120 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
24130 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 need to process
24140 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 SQL from untrus
24150 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d ted sources.** m
24160 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 ight also consid
24170 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f er lowering reso
24180 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e urce limits usin
24190 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 g [sqlite3_limit
241a0 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 ()].** and limit
241b0 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a ing database siz
241c0 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 e using the [max
241d0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 _page_count] [PR
241e0 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 AGMA].** in addi
241f0 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e tion to using an
24200 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a authorizer..**.
24210 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 ** ^(Only a sing
24220 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 le authorizer ca
24230 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e n be in place on
24240 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a database conn
24250 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 ection.** at a t
24260 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 ime. Each call
24270 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 to sqlite3_set_a
24280 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 uthorizer overri
24290 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 des the.** previ
242a0 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 ous call.)^ ^Di
242b0 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 sable the author
242c0 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 izer by installi
242d0 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 ng a NULL callba
242e0 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f ck..** The autho
242f0 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 rizer is disable
24300 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a d by default..**
24310 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a .** The authoriz
24320 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 er callback must
24330 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 not do anything
24340 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 that will modif
24350 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 y.** the databas
24360 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 e connection tha
24370 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 t invoked the au
24380 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
24390 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 k..** Note that
243a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
243b0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 _v2()] and [sqli
243c0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 te3_step()] both
243d0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a modify their.**
243e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
243f0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 tions for the me
24400 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 aning of "modify
24410 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 " in this paragr
24420 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e aph..**.** ^When
24430 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
24440 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 e_v2()] is used
24450 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 to prepare a sta
24460 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 tement, the.** s
24470 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 tatement might b
24480 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 e re-prepared du
24490 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 ring [sqlite3_st
244a0 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a ep()] due to a .
244b0 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 ** schema change
244c0 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 . Hence, the ap
244d0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
244e0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
244f0 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 .** correct auth
24500 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
24510 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 remains in place
24520 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c during the [sql
24530 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a ite3_step()]..**
24540 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 .** ^Note that t
24550 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
24560 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
24570 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a d only during.**
24580 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
24590 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 e()] or its vari
245a0 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 ants. Authoriza
245b0 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 tion is not.** p
245c0 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 erformed during
245d0 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 statement evalua
245e0 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 tion in [sqlite3
245f0 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 _step()], unless
24600 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e .** as stated in
24610 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 the previous pa
24620 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 ragraph, sqlite3
24630 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a _step() invokes.
24640 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 ** sqlite3_prepa
24650 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 re_v2() to repre
24660 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 pare a statement
24670 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 after a schema
24680 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 change..*/.int s
24690 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
246a0 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 rizer(. sqlite3
246b0 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 *,. int (*xAuth
246c0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
246d0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
246e0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
246f0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 const char*),.
24700 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a void *pUserData.
24710 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
24720 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 EF: Authorizer R
24730 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a eturn Codes.**.*
24740 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 * The [sqlite3_s
24750 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 et_authorizer |
24760 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
24770 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 ack function] mu
24780 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 st.** return eit
24790 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 her [SQLITE_OK]
247a0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 or one of these
247b0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e two constants in
247c0 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 order.** to sig
247d0 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 nal SQLite wheth
247e0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 er or not the ac
247f0 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 tion is permitte
24800 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b d. See the.** [
24810 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
24820 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 orizer | authori
24830 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f zer documentatio
24840 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 n] for additiona
24850 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e l.** information
24860 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
24870 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 t SQLITE_IGNORE
24880 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 is also used as
24890 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f a [conflict reso
248a0 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 lution mode].**
248b0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 returned from th
248c0 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f e [sqlite3_vtab_
248d0 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 on_conflict()] i
248e0 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 nterface..*/.#de
248f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 fine SQLITE_DENY
24900 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 1 /* Abort
24910 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
24920 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 t with an error
24930 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
24940 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 E_IGNORE 2 /*
24950 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 Don't allow acce
24960 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 ss, but don't ge
24970 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 nerate an error
24980 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
24990 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 EF: Authorizer A
249a0 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a ction Codes.**.*
249b0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 * The [sqlite3_s
249c0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d et_authorizer()]
249d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 interface regis
249e0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 ters a callback
249f0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 function.** that
24a00 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 is invoked to a
24a10 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e uthorize certain
24a20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 SQL statement a
24a30 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 ctions. The.**
24a40 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
24a50 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
24a60 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 is an integer c
24a70 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 ode that specifi
24a80 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f es.** what actio
24a90 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f n is being autho
24aa0 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 rized. These ar
24ab0 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 e the integer ac
24ac0 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a tion codes that.
24ad0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 ** the authorize
24ae0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 r callback may b
24af0 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 e passed..**.**
24b00 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 These action cod
24b10 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 e values signify
24b20 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 what kind of op
24b30 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 eration is to be
24b40 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 .** authorized.
24b50 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 The 3rd and 4th
24b60 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 parameters to t
24b70 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e he authorization
24b80 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e .** callback fun
24b90 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 ction will be pa
24ba0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c rameters or NULL
24bb0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 depending on wh
24bc0 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 ich of these.**
24bd0 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 codes is used as
24be0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
24bf0 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 meter. ^(The 5t
24c00 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
24c10 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 he.** authorizer
24c20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 callback is the
24c30 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
24c40 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 abase ("main", "
24c50 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 temp",.** etc.)
24c60 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e if applicable.)^
24c70 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d ^The 6th param
24c80 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 eter to the auth
24c90 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a orizer callback.
24ca0 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ** is the name o
24cb0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 f the inner-most
24cc0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 trigger or view
24cd0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 that is respons
24ce0 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 ible for.** the
24cf0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f access attempt o
24d00 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 r NULL if this a
24d10 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 ccess attempt is
24d20 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a directly from.*
24d30 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 * top-level SQL
24d40 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a code..*/./******
24d50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
24d60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
24d70 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a ***** 3rd ******
24d80 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a ****** 4th *****
24d90 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 ******/.#define
24da0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e SQLITE_CREATE_IN
24db0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 DEX 1
24dc0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
24dd0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
24de0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
24df0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 QLITE_CREATE_TAB
24e00 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 LE 2
24e10 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
24e20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
24e30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
24e40 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
24e50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f _INDEX 3 /
24e60 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
24e70 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
24e80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
24e90 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
24ea0 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a TABLE 4 /*
24eb0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
24ec0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
24ed0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
24ee0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 TE_CREATE_TEMP_T
24ef0 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 RIGGER 5 /*
24f00 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
24f10 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
24f20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
24f30 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 E_CREATE_TEMP_VI
24f40 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 EW 6 /* V
24f50 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
24f60 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
24f70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
24f80 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 _CREATE_TRIGGER
24f90 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 7 /* Tr
24fa0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger Name Ta
24fb0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
24fc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
24fd0 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 CREATE_VIEW
24fe0 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 8 /* Vie
24ff0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w Name NUL
25000 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
25010 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
25020 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 ELETE
25030 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 9 /* Tabl
25040 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
25050 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
25060 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
25070 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 OP_INDEX
25080 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 10 /* Index
25090 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
250a0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
250b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
250c0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 P_TABLE
250d0 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 11 /* Table
250e0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
250f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
25100 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
25110 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 _TEMP_INDEX
25120 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 12 /* Index N
25130 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
25140 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
25150 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
25160 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 TEMP_TABLE
25170 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 13 /* Table Na
25180 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
25190 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
251a0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
251b0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 EMP_TRIGGER 1
251c0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 4 /* Trigger N
251d0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
251e0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
251f0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
25200 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 MP_VIEW 15
25210 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
25220 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
25230 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
25240 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 SQLITE_DROP_TRI
25250 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 GGER 16
25260 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
25270 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
25280 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
25290 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 SQLITE_DROP_VIEW
252a0 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 17
252b0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
252c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
252d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
252e0 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 QLITE_INSERT
252f0 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 18
25300 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
25310 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
25320 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
25330 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 LITE_PRAGMA
25340 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 19 /
25350 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 * Pragma Name
25360 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 1st arg or NUL
25370 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c L */.#define SQL
25380 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 ITE_READ
25390 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 /*
253a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
253b0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 Column Name
253c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
253d0 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 TE_SELECT
253e0 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 21 /*
253f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
25400 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
25410 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
25420 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 E_TRANSACTION
25430 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 22 /* O
25440 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e peration N
25450 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
25460 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
25470 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 _UPDATE
25480 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 23 /* Ta
25490 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f ble Name Co
254a0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f lumn Name */
254b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
254c0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 ATTACH
254d0 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 24 /* Fil
254e0 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c ename NUL
254f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
25500 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
25510 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 ETACH
25520 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 25 /* Data
25530 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c base Name NULL
25540 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
25550 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c define SQLITE_AL
25560 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 TER_TABLE
25570 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 26 /* Datab
25580 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 ase Name Table
25590 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
255a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 efine SQLITE_REI
255b0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 NDEX
255c0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 27 /* Index
255d0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
255e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
255f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c fine SQLITE_ANAL
25600 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 YZE
25610 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 28 /* Table N
25620 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
25630 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
25640 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
25650 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 E_VTABLE
25660 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 29 /* Table Na
25670 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e me Module N
25680 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
25690 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 ne SQLITE_DROP_V
256a0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 TABLE 3
256b0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 0 /* Table Nam
256c0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 e Module Na
256d0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
256e0 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f e SQLITE_FUNCTIO
256f0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 N 31
25700 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 /* NULL
25710 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e Function N
25720 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 ame */.#define
25730 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e SQLITE_SAVEPOIN
25740 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 T 32
25750 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 /* Operation
25760 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e Savepoint N
25770 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ame */.#define
25780 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 SQLITE_COPY
25790 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 0
257a0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 /* No longer us
257b0 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
257c0 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 LITE_RECURSIVE
257d0 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 33 /
257e0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 * NULL
257f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
25800 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 */../*.** CAPI
25810 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 3REF: Tracing An
25820 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 d Profiling Func
25830 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a tions.** METHOD:
25840 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 sqlite3.**.** T
25850 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
25860 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55 73 e deprecated. Us
25870 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 e the [sqlite3_t
25880 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 race_v2()] inter
25890 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 face.** instead
258a0 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20 of the routines
258b0 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a described here..
258c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
258d0 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 ines register ca
258e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 llback functions
258f0 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 that can be use
25900 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 d for.** tracing
25910 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 and profiling t
25920 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 he execution of
25930 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a SQL statements..
25940 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 **.** ^The callb
25950 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 ack function reg
25960 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 istered by sqlit
25970 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e e3_trace() is in
25980 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 voked at.** vari
25990 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 ous times when a
259a0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 n SQL statement
259b0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 is being run by
259c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
259d0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
259e0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 3_trace() callba
259f0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 ck is invoked wi
25a00 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 th a UTF-8 rende
25a10 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 ring of the.** S
25a20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 QL statement tex
25a30 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 t as the stateme
25a40 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 nt first begins
25a50 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 executing..** ^(
25a60 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 Additional sqlit
25a70 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 e3_trace() callb
25a80 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 acks might occur
25a90 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 .** as each trig
25aa0 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d gered subprogram
25ab0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 is entered. Th
25ac0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 e callbacks for
25ad0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 triggers.** cont
25ae0 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 ain a UTF-8 SQL
25af0 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 comment that ide
25b00 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 ntifies the trig
25b10 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 ger.)^.**.** The
25b20 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 [SQLITE_TRACE_S
25b30 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 IZE_LIMIT] compi
25b40 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 le-time option c
25b50 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 an be used to li
25b60 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 mit.** the lengt
25b70 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 h of [bound para
25b80 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e meter] expansion
25b90 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f in the output o
25ba0 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 f sqlite3_trace(
25bb0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 )..**.** ^The ca
25bc0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
25bd0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 registered by sq
25be0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 lite3_profile()
25bf0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 is invoked.** as
25c00 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d each SQL statem
25c10 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e ent finishes. ^
25c20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c The profile call
25c30 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a back contains.**
25c40 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 the original st
25c50 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 atement text and
25c60 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 an estimate of
25c70 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a wall-clock time.
25c80 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 ** of how long t
25c90 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f hat statement to
25ca0 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 ok to run. ^The
25cb0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 profile callbac
25cc0 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 k.** time is in
25cd0 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 units of nanosec
25ce0 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 onds, however th
25cf0 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d e current implem
25d00 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f entation.** is o
25d10 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d nly capable of m
25d20 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c illisecond resol
25d30 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 ution so the six
25d40 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 least significa
25d50 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 nt.** digits in
25d60 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 the time are mea
25d70 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 ningless. Futur
25d80 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
25d90 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 Lite.** might pr
25da0 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 ovide greater re
25db0 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 solution on the
25dc0 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 profiler callbac
25dd0 6b 2e 20 20 49 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 k. Invoking.**
25de0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f either [sqlite3_
25df0 74 72 61 63 65 28 29 5d 20 6f 72 20 5b 73 71 6c trace()] or [sql
25e00 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d ite3_trace_v2()]
25e10 20 77 69 6c 6c 20 63 61 6e 63 65 6c 20 74 68 65 will cancel the
25e20 0a 2a 2a 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c .** profile call
25e30 62 61 63 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f back..*/.SQLITE_
25e40 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 DEPRECATED void
25e50 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 *sqlite3_trace(s
25e60 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 qlite3*,. void
25e70 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c (*xTrace)(void*,
25e80 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f const char*), vo
25e90 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 id*);.SQLITE_DEP
25ea0 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 RECATED void *sq
25eb0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 lite3_profile(sq
25ec0 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 lite3*,. void(
25ed0 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a *xProfile)(void*
25ee0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c ,const char*,sql
25ef0 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f ite3_uint64), vo
25f00 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
25f10 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 I3REF: SQL Trace
25f20 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 Event Codes.**
25f30 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 KEYWORDS: SQLITE
25f40 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 _TRACE.**.** The
25f50 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 se constants ide
25f60 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66 ntify classes of
25f70 20 65 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e events that can
25f80 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a be monitored.**
25f90 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 using the [sqli
25fa0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 te3_trace_v2()]
25fb0 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 tracing logic.
25fc0 54 68 65 20 4d 20 61 72 67 75 6d 65 6e 74 0a 2a The M argument.*
25fd0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 * to [sqlite3_tr
25fe0 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 5d ace_v2(D,M,X,P)]
25ff0 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d is an OR-ed com
26000 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 bination of one
26010 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 or more of.** th
26020 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 e following cons
26030 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69 72 tants. ^The fir
26040 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
26050 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 he trace callbac
26060 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 k.** is one of t
26070 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e he following con
26080 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 stants..**.** Ne
26090 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 w tracing consta
260a0 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 nts may be added
260b0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
260c0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 ses..**.** ^A tr
260d0 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 ace callback has
260e0 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a four arguments:
260f0 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 xCallback(T,C,P
26100 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 ,X)..** ^The T a
26110 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f rgument is one o
26120 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 74 79 f the integer ty
26130 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a pe codes above..
26140 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 ** ^The C argume
26150 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 nt is a copy of
26160 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e the context poin
26170 74 65 72 20 70 61 73 73 65 64 20 69 6e 20 61 73 ter passed in as
26180 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 the.** fourth a
26190 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
261a0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e te3_trace_v2()].
261b0 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 .** The P and X
261c0 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f arguments are po
261d0 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 inters whose mea
261e0 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 nings depend on
261f0 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a T..**.** <dl>.**
26200 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f [[SQLITE_TRACE_
26210 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 STMT]] <dt>SQLIT
26220 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 E_TRACE_STMT</dt
26230 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c >.** <dd>^An SQL
26240 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 ITE_TRACE_STMT c
26250 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
26260 65 64 20 77 68 65 6e 20 61 20 70 72 65 70 61 72 ed when a prepar
26270 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 ed statement.**
26280 66 69 72 73 74 20 62 65 67 69 6e 73 20 72 75 6e first begins run
26290 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62 6c ning and possibl
262a0 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65 73 y at other times
262b0 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 during the.** e
262c0 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 xecution of the
262d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
262e0 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74 20 74 nt, such as at t
262f0 68 65 20 73 74 61 72 74 20 6f 66 20 65 61 63 68 he start of each
26300 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62 70 .** trigger subp
26310 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 rogram. ^The P a
26320 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
26330 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b nter to the.** [
26340 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
26350 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67 75 nt]. ^The X argu
26360 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
26370 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 r to a string wh
26380 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e ich.** is the un
26390 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65 78 expanded SQL tex
263a0 74 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 t of the prepare
263b0 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 d statement or a
263c0 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a n SQL comment .*
263d0 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 * that indicates
263e0 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 the invocation
263f0 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 5e of a trigger. ^
26400 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e The callback can
26410 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 compute.** the
26420 73 61 6d 65 20 74 65 78 74 20 74 68 61 74 20 77 same text that w
26430 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20 72 ould have been r
26440 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 6c eturned by the l
26450 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 egacy [sqlite3_t
26460 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 race()].** inter
26470 66 61 63 65 20 62 79 20 75 73 69 6e 67 20 74 68 face by using th
26480 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68 65 e X argument whe
26490 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74 68 20 n X begins with
264a0 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e "--" and invokin
264b0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 g.** [sqlite3_ex
264c0 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f panded_sql(P)] o
264d0 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 therwise..**.**
264e0 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 [[SQLITE_TRACE_P
264f0 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c ROFILE]] <dt>SQL
26500 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c ITE_TRACE_PROFIL
26510 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 E</dt>.** <dd>^A
26520 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 n SQLITE_TRACE_P
26530 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 ROFILE callback
26540 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78 69 provides approxi
26550 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65 0a mately the same.
26560 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 ** information a
26570 73 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 s is provided by
26580 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 the [sqlite3_pr
26590 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 ofile()] callbac
265a0 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 k..** ^The P arg
265b0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
265c0 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 er to the [prepa
265d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 red statement] a
265e0 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 nd the.** X argu
265f0 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 ment points to a
26600 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 64-bit integer
26610 77 68 69 63 68 20 69 73 20 74 68 65 20 65 73 74 which is the est
26620 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 imated of.** the
26630 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 number of nanos
26640 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20 70 econd that the p
26650 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
26660 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a t took to run..*
26670 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54 52 * ^The SQLITE_TR
26680 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c ACE_PROFILE call
26690 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
266a0 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 when the stateme
266b0 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a nt finishes..**.
266c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 ** [[SQLITE_TRAC
266d0 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 E_ROW]] <dt>SQLI
266e0 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 TE_TRACE_ROW</dt
266f0 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c >.** <dd>^An SQL
26700 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 ITE_TRACE_ROW ca
26710 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
26720 64 20 77 68 65 6e 65 76 65 72 20 61 20 70 72 65 d whenever a pre
26730 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
26740 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61 20 73 nt generates a s
26750 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 ingle row of res
26760 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 ult. .** ^The P
26770 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
26780 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 ointer to the [p
26790 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
267a0 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 t] and the.** X
267b0 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 argument is unus
267c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 ed..**.** [[SQLI
267d0 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d TE_TRACE_CLOSE]]
267e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 <dt>SQLITE_TRAC
267f0 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 E_CLOSE</dt>.**
26800 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 <dd>^An SQLITE_T
26810 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 RACE_CLOSE callb
26820 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
26830 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a 2a hen a database.*
26840 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f * connection clo
26850 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 ses..** ^The P a
26860 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
26870 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 nter to the [dat
26880 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
26890 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 ] object.** and
268a0 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 the X argument i
268b0 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 s unused..** </d
268c0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
268d0 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 LITE_TRACE_STMT
268e0 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69 0x01.#defi
268f0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f ne SQLITE_TRACE_
26900 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32 0a PROFILE 0x02.
26910 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
26920 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20 20 RACE_ROW
26930 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 0x04.#define SQL
26940 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 ITE_TRACE_CLOSE
26950 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 0x08../*.**
26960 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 CAPI3REF: SQL T
26970 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 race Hook.** MET
26980 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
26990 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
269a0 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 trace_v2(D,M,X,P
269b0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ) interface regi
269c0 73 74 65 72 73 20 61 20 74 72 61 63 65 20 63 61 sters a trace ca
269d0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 llback.** functi
269e0 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64 61 on X against [da
269f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
26a00 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 n] D, using prop
26a10 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 erty mask M.** a
26a20 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 nd context point
26a30 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20 58 er P. ^If the X
26a40 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 callback is.**
26a50 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20 4d NULL or if the M
26a60 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 mask is zero, t
26a70 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20 64 hen tracing is d
26a80 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a isabled. The.**
26a90 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 M argument shou
26aa0 6c 64 20 62 65 20 74 68 65 20 62 69 74 77 69 73 ld be the bitwis
26ab0 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 e OR-ed combinat
26ac0 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f ion of.** zero o
26ad0 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 r more [SQLITE_T
26ae0 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e RACE] constants.
26af0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c .**.** ^Each cal
26b00 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c 69 l to either sqli
26b10 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 te3_trace() or s
26b20 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 qlite3_trace_v2(
26b30 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 ) overrides .**
26b40 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 (cancels) any pr
26b50 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c ior calls to sql
26b60 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 ite3_trace() or
26b70 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 sqlite3_trace_v2
26b80 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 ()..**.** ^The X
26b90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
26ba0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e oked whenever an
26bb0 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73 20 y of the events
26bc0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a 2a identified by .*
26bd0 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 * mask M occur.
26be0 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72 65 ^The integer re
26bf0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 turn value from
26c00 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
26c10 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e currently.** ign
26c20 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68 69 ored, though thi
26c30 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e 20 s may change in
26c40 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e future releases.
26c50 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d Callback.** im
26c60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 plementations sh
26c70 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72 6f ould return zero
26c80 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75 72 to ensure futur
26c90 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e e compatibility.
26ca0 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 .**.** ^A trace
26cb0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
26cc0 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20 61 72 ked with four ar
26cd0 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 guments: callbac
26ce0 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e k(T,C,P,X)..** ^
26cf0 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 The T argument i
26d00 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 s one of the [SQ
26d10 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 LITE_TRACE].** c
26d20 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 onstants to indi
26d30 63 61 74 65 20 77 68 79 20 74 68 65 20 63 61 6c cate why the cal
26d40 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 lback was invoke
26d50 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 d..** ^The C arg
26d60 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 ument is a copy
26d70 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 of the context p
26d80 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 ointer..** The P
26d90 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 and X arguments
26da0 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 are pointers wh
26db0 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 ose meanings dep
26dc0 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 end on T..**.**
26dd0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 The sqlite3_trac
26de0 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 e_v2() interface
26df0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 is intended to
26e00 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67 61 replace the lega
26e10 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 cy.** interfaces
26e20 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 [sqlite3_trace(
26e30 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
26e40 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 profile()], both
26e50 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 of which.** are
26e60 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a deprecated..*/.
26e70 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 63 int sqlite3_trac
26e80 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a e_v2(. sqlite3*
26e90 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61 ,. unsigned uMa
26ea0 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c sk,. int(*xCall
26eb0 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76 back)(unsigned,v
26ec0 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a oid*,void*,void*
26ed0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78 0a ),. void *pCtx.
26ee0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
26ef0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 EF: Query Progre
26f00 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 ss Callbacks.**
26f10 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
26f20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
26f30 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 e3_progress_hand
26f40 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 ler(D,N,X,P) int
26f50 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 erface causes th
26f60 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 e callback.** fu
26f70 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 nction X to be i
26f80 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 nvoked periodica
26f90 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 lly during long
26fa0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f running calls to
26fb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 .** [sqlite3_exe
26fc0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 c()], [sqlite3_s
26fd0 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 tep()] and [sqli
26fe0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d te3_get_table()]
26ff0 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 for.** database
27000 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 connection D.
27010 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 An example use f
27020 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 or this.** inter
27030 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 face is to keep
27040 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 a GUI updated du
27050 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 ring a large que
27060 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 ry..**.** ^The p
27070 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 arameter P is pa
27080 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 ssed through as
27090 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 the only paramet
270a0 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 er to the .** ca
270b0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
270c0 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 X. ^The paramet
270d0 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 er N is the appr
270e0 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f oximate number o
270f0 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d f .** [virtual m
27100 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 achine instructi
27110 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 ons] that are ev
27120 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 aluated between
27130 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e successive.** in
27140 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 vocations of the
27150 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 callback X. ^I
27160 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e f N is less than
27170 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 one then the pr
27180 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 ogress.** handle
27190 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a r is disabled..*
271a0 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e *.** ^Only a sin
271b0 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e gle progress han
271c0 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 dler may be defi
271d0 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 ned at one time
271e0 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 per.** [database
271f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 connection]; se
27200 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 tting a new prog
27210 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e ress handler can
27220 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 cels the.** old
27230 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 one. ^Setting p
27240 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 arameter X to NU
27250 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 LL disables the
27260 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
27270 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 ..** ^The progre
27280 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c ss handler is al
27290 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 so disabled by s
272a0 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 etting N to a va
272b0 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e lue less.** than
272c0 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 1..**.** ^If th
272d0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 e progress callb
272e0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ack returns non-
272f0 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 zero, the operat
27300 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 ion is.** interr
27310 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 upted. This fea
27320 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 ture can be used
27330 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a to implement a.
27340 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 ** "Cancel" butt
27350 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 on on a GUI prog
27360 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e ress dialog box.
27370 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 .**.** The progr
27380 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c ess handler call
27390 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f back must not do
273a0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 anything that w
273b0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 ill modify.** th
273c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
273d0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b ction that invok
273e0 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 ed the progress
273f0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 handler..** Note
27400 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 that [sqlite3_p
27410 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
27420 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
27430 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 ] both modify th
27440 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 eir.** database
27450 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 connections for
27460 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 the meaning of "
27470 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 modify" in this
27480 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f paragraph..**.*/
27490 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 .void sqlite3_pr
274a0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 ogress_handler(s
274b0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e qlite3*, int, in
274c0 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 t(*)(void*), voi
274d0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
274e0 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 3REF: Opening A
274f0 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e New Database Con
27500 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 nection.** CONST
27510 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a RUCTOR: sqlite3.
27520 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
27530 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 tines open an SQ
27540 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 Lite database fi
27550 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 le as specified
27560 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e by the .** filen
27570 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 ame argument. ^T
27580 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
27590 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 ment is interpre
275a0 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 ted as UTF-8 for
275b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
275c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
275d0 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 pen_v2() and as
275e0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 UTF-16 in the na
275f0 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 tive byte.** ord
27600 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f er for sqlite3_o
27610 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 pen16(). ^(A [da
27620 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
27630 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 n] handle is usu
27640 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 ally.** returned
27650 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 in *ppDb, even
27660 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 if an error occu
27670 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 rs. The only ex
27680 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a ception is that.
27690 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 ** if SQLite is
276a0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
276b0 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c te memory to hol
276c0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 d the [sqlite3]
276d0 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c object,.** a NUL
276e0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 L will be writte
276f0 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 n into *ppDb ins
27700 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 tead of a pointe
27710 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 r to the [sqlite
27720 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 3].** object.)^
27730 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 ^(If the databas
27740 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 e is opened (and
27750 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 /or created) suc
27760 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a cessfully, then.
27770 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 ** [SQLITE_OK] i
27780 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 s returned. Oth
27790 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 erwise an [error
277a0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
277b0 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 ed.)^ ^The.** [s
277c0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
277d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 or [sqlite3_err
277e0 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 msg16()] routine
277f0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f s can be used to
27800 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e obtain.** an En
27810 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 glish language d
27820 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 escription of th
27830 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e e error followin
27840 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 g a failure of a
27850 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c ny.** of the sql
27860 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 ite3_open() rout
27870 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ines..**.** ^The
27880 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e default encodin
27890 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 g will be UTF-8
278a0 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72 for databases cr
278b0 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 eated using.** s
278c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 qlite3_open() or
278d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
278e0 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c (). ^The defaul
278f0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 t encoding for d
27900 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 atabases.** crea
27910 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 ted using sqlite
27920 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 3_open16() will
27930 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 be UTF-16 in the
27940 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
27950 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 er..**.** Whethe
27960 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f r or not an erro
27970 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 r occurs when it
27980 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f is opened, reso
27990 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 urces.** associa
279a0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 ted with the [da
279b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
279c0 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 n] handle should
279d0 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a be released by.
279e0 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f ** passing it to
279f0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
27a00 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f )] when it is no
27a10 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 longer required
27a20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
27a30 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e te3_open_v2() in
27a40 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 terface works li
27a50 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ke sqlite3_open(
27a60 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 ).** except that
27a70 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 it accepts two
27a80 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d additional param
27a90 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 eters for additi
27aa0 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 onal control.**
27ab0 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 over the new dat
27ac0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
27ad0 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 . ^(The flags p
27ae0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 arameter to.** s
27af0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
27b00 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 can take one of
27b10 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e .** the followin
27b20 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 g three values,
27b30 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 optionally combi
27b40 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a ned with the .**
27b50 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f [SQLITE_OPEN_NO
27b60 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f MUTEX], [SQLITE_
27b70 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c OPEN_FULLMUTEX],
27b80 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 [SQLITE_OPEN_SH
27b90 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b AREDCACHE],.** [
27ba0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
27bb0 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f ATECACHE], and/o
27bc0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 r [SQLITE_OPEN_U
27bd0 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a RI] flags:)^.**.
27be0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 ** <dl>.** ^(<dt
27bf0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 >[SQLITE_OPEN_RE
27c00 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 ADONLY]</dt>.**
27c10 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 <dd>The database
27c20 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 is opened in re
27c30 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 ad-only mode. I
27c40 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 f the database d
27c50 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 oes not.** alrea
27c60 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 dy exist, an err
27c70 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c or is returned.<
27c80 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c /dd>)^.**.** ^(<
27c90 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f dt>[SQLITE_OPEN_
27ca0 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a READWRITE]</dt>.
27cb0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 ** <dd>The datab
27cc0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f ase is opened fo
27cd0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 r reading and wr
27ce0 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c iting if possibl
27cf0 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a e, or reading.**
27d00 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c only if the fil
27d10 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 e is write prote
27d20 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 cted by the oper
27d30 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 ating system. I
27d40 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 n either.** case
27d50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 the database mu
27d60 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 st already exist
27d70 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 , otherwise an e
27d80 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
27d90 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e .</dd>)^.**.** ^
27da0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 (<dt>[SQLITE_OPE
27db0 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b N_READWRITE] | [
27dc0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
27dd0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TE]</dt>.** <dd>
27de0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
27df0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 opened for readi
27e00 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 ng and writing,
27e10 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 and is created i
27e20 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 f.** it does not
27e30 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 already exist.
27e40 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 This is the beha
27e50 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 vior that is alw
27e60 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 ays used for.**
27e70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 sqlite3_open() a
27e80 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 nd sqlite3_open1
27e90 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 6().</dd>)^.** <
27ea0 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 /dl>.**.** If th
27eb0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
27ec0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
27ed0 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 v2() is not one
27ee0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e of the.** combin
27ef0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f ations shown abo
27f00 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f ve optionally co
27f10 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 mbined with othe
27f20 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 r.** [SQLITE_OPE
27f30 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c N_READONLY | SQL
27f40 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d ITE_OPEN_* bits]
27f50 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 .** then the beh
27f60 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
27f70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ed..**.** ^If th
27f80 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e e [SQLITE_OPEN_N
27f90 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 OMUTEX] flag is
27fa0 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 set, then the da
27fb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
27fc0 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 n.** opens in th
27fd0 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b e multi-thread [
27fe0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
27ff0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 as long as the s
28000 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 ingle-thread.**
28010 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 mode has not bee
28020 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 n set at compile
28030 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 -time or start-t
28040 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a ime. ^If the.**
28050 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 [SQLITE_OPEN_FU
28060 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 LLMUTEX] flag is
28070 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 set then the da
28080 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
28090 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 n opens.** in th
280a0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 e serialized [th
280b0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e reading mode] un
280c0 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 less single-thre
280d0 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f ad was.** previo
280e0 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 usly selected at
280f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 compile-time or
28100 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 start-time..**
28110 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 ^The [SQLITE_OPE
28120 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 N_SHAREDCACHE] f
28130 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 lag causes the d
28140 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
28150 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 on to be.** elig
28160 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 ible to use [sha
28170 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c red cache mode],
28180 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 regardless of w
28190 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 hether or not sh
281a0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 ared.** cache is
281b0 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b enabled using [
281c0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 sqlite3_enable_s
281d0 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 hared_cache()].
281e0 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 ^The.** [SQLITE
281f0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 _OPEN_PRIVATECAC
28200 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 HE] flag causes
28210 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
28220 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a nection to not.*
28230 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e * participate in
28240 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d [shared cache m
28250 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 ode] even if it
28260 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a is enabled..**.*
28270 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 * ^The fourth pa
28280 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
28290 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
282a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a the name of the.
282b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d ** [sqlite3_vfs]
282c0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 object that def
282d0 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 ines the operati
282e0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 ng system interf
282f0 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ace that.** the
28300 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e new database con
28310 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 nection should u
28320 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 se. ^If the fou
28330 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
28340 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 .** a NULL point
28350 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 er then the defa
28360 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
28370 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 ] object is used
28380 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
28390 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 filename is ":me
283a0 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 mory:", then a p
283b0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 rivate, temporar
283c0 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 y in-memory data
283d0 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 base.** is creat
283e0 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 ed for the conne
283f0 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e ction. ^This in
28400 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
28410 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 will vanish whe
28420 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 n.** the databas
28430 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
28440 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 closed. Future
28450 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
28460 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 te might.** make
28470 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e use of addition
28480 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e al special filen
28490 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 ames that begin
284a0 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 with the ":" cha
284b0 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 racter..** It is
284c0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 recommended tha
284d0 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 t when a databas
284e0 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 e filename actua
284f0 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 lly does begin w
28500 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 ith.** a ":" cha
28510 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c racter you shoul
28520 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c d prefix the fil
28530 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 ename with a pat
28540 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a hname such as.**
28550 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 "./" to avoid a
28560 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 mbiguity..**.**
28570 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 ^If the filename
28580 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 is an empty str
28590 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 ing, then a priv
285a0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a ate, temporary.*
285b0 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 * on-disk databa
285c0 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 se will be creat
285d0 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 ed. ^This priva
285e0 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c te database will
285f0 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 be.** automatic
28600 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 ally deleted as
28610 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 soon as the data
28620 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
28630 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a is closed..**.**
28640 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 [[URI filenames
28650 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e in sqlite3_open
28660 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c ()]] <h3>URI Fil
28670 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a enames</h3>.**.*
28680 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e * ^If [URI filen
28690 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 ame] interpretat
286a0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 ion is enabled,
286b0 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 and the filename
286c0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 argument.** beg
286d0 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 ins with "file:"
286e0 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e , then the filen
286f0 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 ame is interpret
28700 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 ed as a URI. ^UR
28710 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e I.** filename in
28720 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 terpretation is
28730 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b enabled if the [
28740 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d SQLITE_OPEN_URI]
28750 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 flag is.** set
28760 69 6e 20 74 68 65 20 74 68 69 72 64 20 61 72 67 in the third arg
28770 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
28780 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 _open_v2(), or i
28790 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e f it has.** been
287a0 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c enabled globall
287b0 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c y using the [SQL
287c0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 ITE_CONFIG_URI]
287d0 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a option with the.
287e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
287f0 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 ig()] method or
28800 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 by the [SQLITE_U
28810 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d SE_URI] compile-
28820 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 time option..**
28830 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 URI filename int
28840 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 erpretation is t
28850 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 urned off.** by
28860 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 default, but fut
28870 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
28880 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 SQLite might ena
28890 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 ble URI filename
288a0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 .** interpretati
288b0 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 on by default.
288c0 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 See "[URI filena
288d0 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 mes]" for additi
288e0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 onal.** informat
288f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 ion..**.** URI f
28900 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 ilenames are par
28910 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f sed according to
28920 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 RFC 3986. ^If t
28930 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 he URI contains
28940 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c an.** authority,
28950 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 then it must be
28960 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 either an empty
28970 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 string or the s
28980 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c tring .** "local
28990 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 host". ^If the a
289a0 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 uthority is not
289b0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 an empty string
289c0 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 or "localhost",
289d0 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 an .** error is
289e0 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 returned to the
289f0 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 caller. ^The fra
28a00 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 gment component
28a10 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a of a URI, if .**
28a20 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e present, is ign
28a30 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c ored..**.** ^SQL
28a40 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 ite uses the pat
28a50 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 h component of t
28a60 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 he URI as the na
28a70 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 me of the disk f
28a80 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e ile.** which con
28a90 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 tains the databa
28aa0 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 se. ^If the path
28ab0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 begins with a '
28ac0 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a /' character, .*
28ad0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 * then it is int
28ae0 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 erpreted as an a
28af0 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 bsolute path. ^I
28b00 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 f the path does
28b10 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 not begin .** wi
28b20 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e th a '/' (meanin
28b30 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f g that the autho
28b40 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 rity section is
28b50 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 omitted from the
28b60 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 URI).** then th
28b70 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 e path is interp
28b80 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 reted as a relat
28b90 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 ive path. .** ^(
28ba0 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 On windows, the
28bb0 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 first component
28bc0 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 of an absolute p
28bd0 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 ath .** is a dri
28be0 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e ve specification
28bf0 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a (e.g. "C:").)^.
28c00 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 **.** [[core URI
28c10 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
28c20 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 s]].** The query
28c30 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 component of a
28c40 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 URI may contain
28c50 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 parameters that
28c60 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a are interpreted.
28c70 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c ** either by SQL
28c80 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 ite itself, or b
28c90 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f y a [VFS | custo
28ca0 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 m VFS implementa
28cb0 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 tion]..** SQLite
28cc0 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 and its built-i
28cd0 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 n [VFSes] interp
28ce0 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f ret the.** follo
28cf0 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d wing query param
28d00 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c eters:.**.** <ul
28d10 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 >.** <li> <b>v
28d20 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 fs</b>: ^The "vf
28d30 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 s" parameter may
28d40 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 be used to spec
28d50 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a ify the name of.
28d60 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a ** a VFS obj
28d70 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 ect that provide
28d80 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 s the operating
28d90 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 system interface
28da0 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 that should.**
28db0 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 be used to a
28dc0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 ccess the databa
28dd0 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e se file on disk.
28de0 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e ^If this option
28df0 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 is set to.**
28e00 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e an empty strin
28e10 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 g the default VF
28e20 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 S object is used
28e30 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e . ^Specifying an
28e40 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 unknown.**
28e50 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e VFS is an error.
28e60 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 ^If sqlite3_ope
28e70 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 n_v2() is used a
28e80 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f nd the vfs optio
28e90 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 n is.** pres
28ea0 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 ent, then the VF
28eb0 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 S specified by t
28ec0 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 he option takes
28ed0 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a precedence over.
28ee0 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 ** the value
28ef0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 passed as the f
28f00 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
28f10 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
28f20 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c v2()..**.** <l
28f30 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 i> <b>mode</b>:
28f40 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d ^(The mode param
28f50 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 eter may be set
28f60 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 to either "ro",
28f70 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 "rw",.** "rw
28f80 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e c", or "memory".
28f90 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 Attempting to s
28fa0 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 et it to any oth
28fb0 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 er value is.**
28fc0 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a an error)^. .
28fd0 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 ** ^If "ro"
28fe0 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 is specified, th
28ff0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
29000 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
29010 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 ad-only .**
29020 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 access, just as
29030 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f if the [SQLITE_O
29040 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c PEN_READONLY] fl
29050 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 ag had been set
29060 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 in the .** t
29070 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f hird argument to
29080 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
29090 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 (). ^If the mode
290a0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 option is set t
290b0 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 o .** "rw",
290c0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
290d0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 e is opened for
290e0 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 read-write (but
290f0 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 not create) .**
29100 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 access, as i
29110 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 f SQLITE_OPEN_RE
29120 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 ADWRITE (but not
29130 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 SQLITE_OPEN_CRE
29140 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 ATE) had .**
29150 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 been set. ^Valu
29160 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 e "rwc" is equiv
29170 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 alent to setting
29180 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 both .** SQ
29190 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
291a0 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f ITE and SQLITE_O
291b0 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 PEN_CREATE. ^If
291c0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e the mode option
291d0 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 is.** set t
291e0 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 o "memory" then
291f0 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 a pure [in-memor
29200 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 y database] that
29210 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 never reads.**
29220 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 or writes fr
29230 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e om disk is used.
29240 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 ^It is an error
29250 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 to specify a va
29260 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 lue for.** t
29270 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 he mode paramete
29280 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 r that is less r
29290 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 estrictive than
292a0 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 that specified b
292b0 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 y.** the fla
292c0 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 gs passed in the
292d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
292e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
292f0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c _v2()..**.** <
29300 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e li> <b>cache</b>
29310 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 : ^The cache par
29320 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 ameter may be se
29330 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 t to either "sha
29340 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 red" or.** "
29350 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 private". ^Setti
29360 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 ng it to "shared
29370 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 " is equivalent
29380 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a to setting the.*
29390 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 * SQLITE_OPE
293a0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 N_SHAREDCACHE bi
293b0 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 t in the flags a
293c0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 rgument passed t
293d0 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 o.** sqlite3
293e0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 _open_v2(). ^Set
293f0 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 ting the cache p
29400 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 arameter to "pri
29410 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 vate" is .**
29420 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 equivalent to s
29430 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 etting the SQLIT
29440 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 E_OPEN_PRIVATECA
29450 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 CHE bit..**
29460 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ^If sqlite3_open
29470 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e _v2() is used an
29480 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 d the "cache" pa
29490 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 rameter is prese
294a0 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 nt in.** a U
294b0 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 RI filename, its
294c0 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 value overrides
294d0 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 any behavior re
294e0 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 quested by setti
294f0 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 ng.** SQLITE
29500 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 _OPEN_PRIVATECAC
29510 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 HE or SQLITE_OPE
29520 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c N_SHAREDCACHE fl
29530 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 ag..**.** <li>
29540 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 <b>psow</b>: ^Th
29550 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 e psow parameter
29560 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 indicates wheth
29570 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a er or not the.**
29580 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 [powersafe
29590 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 overwrite] prope
295a0 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 rty does or does
295b0 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 not apply to th
295c0 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 e.** storage
295d0 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 media on which
295e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
295f0 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a e resides..**.**
29600 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b <li> <b>nolock
29610 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 </b>: ^The noloc
29620 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 k parameter is a
29630 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 boolean query p
29640 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 arameter.**
29650 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73 which if set dis
29660 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 ables file locki
29670 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a ng in rollback j
29680 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 ournal modes. T
29690 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 his.** is us
296a0 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 eful for accessi
296b0 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e ng a database on
296c0 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 a filesystem th
296d0 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 at does not.**
296e0 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 support locki
296f0 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 ng. Caution: D
29700 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 atabase corrupti
29710 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 on might result
29720 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 if two.** or
29730 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 more processes
29740 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d write to the sam
29750 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 e database and a
29760 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a ny one of those.
29770 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 ** processes
29780 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a uses nolock=1..
29790 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 **.** <li> <b>i
297a0 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 mmutable</b>: ^T
297b0 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 he immutable par
297c0 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c ameter is a bool
297d0 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 ean query.**
297e0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 parameter that
297f0 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 indicates that t
29800 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
29810 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a is stored on.**
29820 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d read-only m
29830 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d edia. ^When imm
29840 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 utable is set, S
29850 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 QLite assumes th
29860 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 at the.** da
29870 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e tabase file cann
29880 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 ot be changed, e
29890 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 ven by a process
298a0 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 with higher.**
298b0 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 privilege, a
298c0 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 nd so the databa
298d0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 se is opened rea
298e0 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c d-only and all l
298f0 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e ocking.** an
29900 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 d change detecti
29910 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 on is disabled.
29920 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e Caution: Settin
29930 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a g the immutable.
29940 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 ** property
29950 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 on a database fi
29960 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 le that does in
29970 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 fact change can
29980 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e result.** in
29990 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 incorrect query
299a0 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 results and/or
299b0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d [SQLITE_CORRUPT]
299c0 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 errors..**
299d0 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 See also: [SQLIT
299e0 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c E_IOCAP_IMMUTABL
299f0 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a E]..** .**
29a00 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 </ul>.**.** ^Sp
29a10 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e ecifying an unkn
29a20 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e own parameter in
29a30 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f the query compo
29a40 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 nent of a URI is
29a50 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 not an.** error
29a60 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
29a70 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 ns of SQLite mig
29a80 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 ht understand ad
29a90 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a ditional query.*
29aa0 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 * parameters. S
29ab0 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d ee "[query param
29ac0 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 eters with speci
29ad0 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 al meaning to SQ
29ae0 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 Lite]" for.** ad
29af0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
29b00 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 tion..**.** [[UR
29b10 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 I filename examp
29b20 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 les]] <h3>URI fi
29b30 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c lename examples<
29b40 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c /h3>.**.** <tabl
29b50 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 e border="1" ali
29b60 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 gn=center cellpa
29b70 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e dding=5>.** <tr>
29b80 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d <th> URI filenam
29b90 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a es <th> Results.
29ba0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
29bb0 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a :data.db <td> .*
29bc0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 * Open
29bd0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 the file "data.d
29be0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e b" in the curren
29bf0 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 t directory..**
29c00 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 <tr><td> file:/h
29c10 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
29c20 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 <br>.**
29c30 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 file:///home/fr
29c40 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 ed/data.db <br>
29c50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c .** fil
29c60 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f e://localhost/ho
29c70 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 me/fred/data.db
29c80 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 <br> <td> .**
29c90 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 Open the
29ca0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f database file "/
29cb0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
29cc0 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 b"..** <tr><td>
29cd0 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f file://darkstar/
29ce0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
29cf0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 b <td> .**
29d00 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 An error. "d
29d10 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 arkstar" is not
29d20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 a recognized aut
29d30 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c hority..** <tr><
29d40 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d td style="white-
29d50 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a space:nowrap"> .
29d60 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 ** file
29d70 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 :///C:/Documents
29d80 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 %20and%20Setting
29d90 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 s/fred/Desktop/d
29da0 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 ata.db.** <t
29db0 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a d> Windows only:
29dc0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 Open the file "
29dd0 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 data.db" on fred
29de0 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 's desktop on dr
29df0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ive.**
29e00 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 C:. Note that th
29e10 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 e %20 escaping i
29e20 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 n this example i
29e30 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a s not strictly .
29e40 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 ** nece
29e50 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 ssary - space ch
29e60 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 aracters can be
29e70 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a used literally.*
29e80 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 * in UR
29e90 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 I filenames..**
29ea0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 <tr><td> file:da
29eb0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 ta.db?mode=ro&ca
29ec0 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e che=private <td>
29ed0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 .** Op
29ee0 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 en file "data.db
29ef0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 " in the current
29f00 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 directory for r
29f10 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e ead-only access.
29f20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 .** Reg
29f30 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
29f40 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 er or not shared
29f50 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 -cache mode is e
29f60 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 nabled by.**
29f70 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 default, u
29f80 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 se a private cac
29f90 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 he..** <tr><td>
29fa0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f file:/home/fred/
29fb0 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 data.db?vfs=unix
29fc0 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a -dotfile <td>.**
29fd0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 Open f
29fe0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f ile "/home/fred/
29ff0 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 data.db". Use th
2a000 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 e special VFS "u
2a010 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 nix-dotfile".**
2a020 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73 that us
2a030 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 es dot-files in
2a040 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 place of posix a
2a050 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e dvisory locking.
2a060 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c .** <tr><td> fil
2a070 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 e:data.db?mode=r
2a080 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a eadonly <td> .**
2a090 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 An err
2a0a0 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 or. "readonly" i
2a0b0 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 s not a valid op
2a0c0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f tion for the "mo
2a0d0 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a de" parameter..*
2a0e0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a * </table>.**.**
2a0f0 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 ^URI hexadecima
2a100 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 l escape sequenc
2a110 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 es (%HH) are sup
2a120 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 ported within th
2a130 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 e path and.** qu
2a140 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f ery components o
2a150 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 f a URI. A hexad
2a160 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 ecimal escape se
2a170 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 quence consists
2a180 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 of a.** percent
2a190 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c sign - "%" - fol
2a1a0 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 lowed by exactly
2a1b0 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c two hexadecimal
2a1c0 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 digits .** spec
2a1d0 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 ifying an octet
2a1e0 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 value. ^Before t
2a1f0 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 he path or query
2a200 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 components of a
2a210 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 .** URI filename
2a220 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 are interpreted
2a230 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 , they are encod
2a240 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 ed using UTF-8 a
2a250 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 nd all .** hexad
2a260 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 ecimal escape se
2a270 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 quences replaced
2a280 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 by a single byt
2a290 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 e containing the
2a2a0 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e .** correspondin
2a2b0 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 g octet. If this
2a2c0 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 process generat
2a2d0 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 es an invalid UT
2a2e0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a F-8 encoding,.**
2a2f0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
2a300 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
2a310 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e * <b>Note to Win
2a320 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 dows users:</b>
2a330 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 The encoding us
2a340 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e ed for the filen
2a350 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ame argument.**
2a360 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 of sqlite3_open(
2a370 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 ) and sqlite3_op
2a380 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 en_v2() must be
2a390 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 UTF-8, not whate
2a3a0 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 ver.** codepage
2a3b0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 is currently def
2a3c0 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 ined. Filenames
2a3d0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 containing inte
2a3e0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 rnational.** cha
2a3f0 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 racters must be
2a400 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 converted to UTF
2a410 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 -8 prior to pass
2a420 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a ing them into.**
2a430 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
2a440 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
2a450 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e v2()..**.** <b>N
2a460 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 ote to Windows R
2a470 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 untime users:</b
2a480 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 > The temporary
2a490 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 directory must
2a4a0 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 be set.** prior
2a4b0 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 to calling sqlit
2a4c0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c e3_open() or sql
2a4d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 ite3_open_v2().
2a4e0 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 Otherwise, vari
2a4f0 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 ous.** features
2a500 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 that require the
2a510 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 use of temporar
2a520 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c y files may fail
2a530 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
2a540 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f : [sqlite3_temp_
2a550 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e directory].*/.in
2a560 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a t sqlite3_open(.
2a570 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 const char *fi
2a580 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
2a590 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
2a5a0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 UTF-8) */. sqli
2a5b0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 te3 **ppDb
2a5c0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
2a5d0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
2a5e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f );.int sqlite3_o
2a5f0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 pen16(. const v
2a600 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 oid *filename,
2a610 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
2a620 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a ename (UTF-16) *
2a630 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 /. sqlite3 **pp
2a640 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f Db /* O
2a650 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 UT: SQLite db ha
2a660 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 ndle */.);.int s
2a670 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a qlite3_open_v2(.
2a680 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 const char *fi
2a690 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
2a6a0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
2a6b0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 UTF-8) */. sqli
2a6c0 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 te3 **ppDb,
2a6d0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
2a6e0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
2a6f0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 int flags,
2a700 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 /* Fla
2a710 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 gs */. const ch
2a720 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 ar *zVfs
2a730 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d /* Name of VFS m
2a740 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a odule to use */.
2a750 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2a760 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 EF: Obtain Value
2a770 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 s For URI Parame
2a780 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ters.**.** These
2a790 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 are utility rou
2a7a0 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f tines, useful to
2a7b0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
2a7c0 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b ions, that check
2a7d0 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 .** to see if a
2a7e0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 database file wa
2a7f0 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e s a URI that con
2a800 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 tained a specifi
2a810 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 c query .** para
2a820 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f meter, and if so
2a830 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c obtains the val
2a840 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 ue of that query
2a850 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
2a860 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 * If F is the da
2a870 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
2a880 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 pointer passed i
2a890 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 nto the xOpen()
2a8a0 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 method of .** a
2a8b0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
2a8c0 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 on when the flag
2a8d0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 s parameter to x
2a8e0 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f Open() has one o
2a8f0 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 r .** more of th
2a900 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 e [SQLITE_OPEN_U
2a910 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f RI] or [SQLITE_O
2a920 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 PEN_MAIN_DB] bit
2a930 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 s set and.** P i
2a940 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
2a950 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 e query paramete
2a960 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 r, then.** sqlit
2a970 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 e3_uri_parameter
2a980 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 (F,P) returns th
2a990 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 e value of the P
2a9a0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 .** parameter if
2a9b0 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 it exists or a
2a9c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 NULL pointer if
2a9d0 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 P does not appea
2a9e0 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 r as a .** query
2a9f0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e parameter on F.
2aa00 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 If P is a quer
2aa10 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 y parameter of F
2aa20 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 .** has no expli
2aa30 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 cit value, then
2aa40 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 sqlite3_uri_para
2aa50 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 meter(F,P) retur
2aa60 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 ns.** a pointer
2aa70 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 to an empty stri
2aa80 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ng..**.** The sq
2aa90 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
2aaa0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 n(F,P,B) routine
2aab0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 assumes that P
2aac0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 is a boolean.**
2aad0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 parameter and re
2aae0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f turns true (1) o
2aaf0 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f r false (0) acco
2ab00 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c rding to the val
2ab10 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 ue.** of P. The
2ab20 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
2ab30 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 lean(F,P,B) rout
2ab40 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 ine returns true
2ab50 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 (1) if the.** v
2ab60 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 alue of query pa
2ab70 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 rameter P is one
2ab80 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 of "yes", "true
2ab90 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e ", or "on" in an
2aba0 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 y.** case or if
2abb0 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 the value begins
2abc0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f with a non-zero
2abd0 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a number. The .*
2abe0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f * sqlite3_uri_bo
2abf0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 olean(F,P,B) rou
2ac00 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 tines returns fa
2ac10 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 lse (0) if the v
2ac20 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 alue of.** query
2ac30 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 parameter P is
2ac40 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 one of "no", "fa
2ac50 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 lse", or "off" i
2ac60 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a n any case or.**
2ac70 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 if the value be
2ac80 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 gins with a nume
2ac90 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 ric zero. If P
2aca0 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a is not a query.*
2acb0 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 * parameter on F
2acc0 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 or if the value
2acd0 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f of P is does no
2ace0 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 t match any of t
2acf0 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 he.** above, the
2ad00 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f n sqlite3_uri_bo
2ad10 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 olean(F,P,B) ret
2ad20 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a urns (B!=0)..**.
2ad30 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 ** The sqlite3_u
2ad40 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 ri_int64(F,P,D)
2ad50 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 routine converts
2ad60 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
2ad70 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 into a.** 64-bit
2ad80 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 signed integer
2ad90 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 and returns that
2ada0 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 integer, or D i
2adb0 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 f P does not.**
2adc0 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 exist. If the v
2add0 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d alue of P is som
2ade0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 ething other tha
2adf0 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 n an integer, th
2ae00 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 en.** zero is re
2ae10 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 turned..** .** I
2ae20 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f f F is a NULL po
2ae30 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 inter, then sqli
2ae40 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 te3_uri_paramete
2ae50 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e r(F,P) returns N
2ae60 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 ULL and.** sqlit
2ae70 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
2ae80 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e ,P,B) returns B.
2ae90 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 If F is not a
2aea0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 NULL pointer and
2aeb0 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 .** is not a dat
2aec0 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e abase file pathn
2aed0 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 ame pointer that
2aee0 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 SQLite passed i
2aef0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a nto the xOpen.**
2af00 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 VFS method, the
2af10 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f n the behavior o
2af20 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 f this routine i
2af30 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
2af40 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 probably.** unde
2af50 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 53 sirable..**.** S
2af60 65 65 20 74 68 65 20 5b 55 52 49 20 66 69 6c 65 ee the [URI file
2af70 6e 61 6d 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 name] documentat
2af80 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ion for addition
2af90 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
2afa0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
2afb0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d qlite3_uri_param
2afc0 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 eter(const char
2afd0 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 *zFilename, cons
2afe0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b t char *zParam);
2aff0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 .int sqlite3_uri
2b000 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 _boolean(const c
2b010 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 har *zFile, cons
2b020 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 t char *zParam,
2b030 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 int bDefault);.s
2b040 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
2b050 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 ite3_uri_int64(c
2b060 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 onst char*, cons
2b070 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 t char*, sqlite3
2b080 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a _int64);.../*.**
2b090 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 CAPI3REF: Error
2b0a0 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 Codes And Messa
2b0b0 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ges.** METHOD: s
2b0c0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 qlite3.**.** ^If
2b0d0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
2b0e0 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 sqlite3_* API c
2b0f0 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 all associated w
2b100 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 ith .** [databas
2b110 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 e connection] D
2b120 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 failed, then the
2b130 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
2b140 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a (D) interface.**
2b150 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
2b160 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 eric [result cod
2b170 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 e] or [extended
2b180 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 result code] for
2b190 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c that.** API cal
2b1a0 6c 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 l..** ^The sqlit
2b1b0 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 e3_extended_errc
2b1c0 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 ode().** interfa
2b1d0 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 ce is the same e
2b1e0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c xcept that it al
2b1f0 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 ways returns the
2b200 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 .** [extended r
2b210 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e esult code] even
2b220 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 when extended r
2b230 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a esult codes are.
2b240 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a ** disabled..**.
2b250 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 ** The values re
2b260 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
2b270 33 5f 65 72 72 63 6f 64 65 28 29 20 61 6e 64 2f 3_errcode() and/
2b280 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 or.** sqlite3_ex
2b290 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 tended_errcode()
2b2a0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 77 69 might change wi
2b2b0 74 68 20 65 61 63 68 20 41 50 49 20 63 61 6c 6c th each API call
2b2c0 2e 0a 2a 2a 20 45 78 63 65 70 74 2c 20 74 68 65 ..** Except, the
2b2d0 72 65 20 61 72 65 20 73 6f 6d 65 20 69 6e 74 65 re are some inte
2b2e0 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65 20 rfaces that are
2b2f0 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 6e 65 guaranteed to ne
2b300 76 65 72 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 ver.** change th
2b310 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 65 e value of the e
2b320 72 72 6f 72 20 63 6f 64 65 2e 20 20 54 68 65 20 rror code. The
2b330 65 72 72 6f 72 2d 63 6f 64 65 20 70 72 65 73 65 error-code prese
2b340 72 76 69 6e 67 0a 2a 2a 20 69 6e 74 65 72 66 61 rving.** interfa
2b350 63 65 73 20 61 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c ces are:.**.** <
2b360 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 ul>.** <li> sqli
2b370 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a te3_errcode().**
2b380 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 78 <li> sqlite3_ex
2b390 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 tended_errcode()
2b3a0 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 .** <li> sqlite3
2b3b0 5f 65 72 72 6d 73 67 28 29 0a 2a 2a 20 3c 6c 69 _errmsg().** <li
2b3c0 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 > sqlite3_errmsg
2b3d0 31 36 28 29 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 16().** </ul>.**
2b3e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2b3f0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 _errmsg() and sq
2b400 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
2b410 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d return English-
2b420 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 language.** text
2b430 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 that describes
2b440 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 the error, as ei
2b450 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 ther UTF-8 or UT
2b460 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c F-16 respectivel
2b470 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 y..** ^(Memory t
2b480 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 o hold the error
2b490 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
2b4a0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 is managed inter
2b4b0 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 nally..** The ap
2b4c0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e plication does n
2b4d0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 ot need to worry
2b4e0 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 about freeing t
2b4f0 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f he result..** Ho
2b500 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 wever, the error
2b510 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 string might be
2b520 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 overwritten or
2b530 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a deallocated by.*
2b540 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c * subsequent cal
2b550 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 ls to other SQLi
2b560 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e te interface fun
2b570 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 ctions.)^.**.**
2b580 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 ^The sqlite3_err
2b590 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 str() interface
2b5a0 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c returns the Engl
2b5b0 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 ish-language tex
2b5c0 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 t.** that descri
2b5d0 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 bes the [result
2b5e0 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e code], as UTF-8.
2b5f0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 .** ^(Memory to
2b600 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d hold the error m
2b610 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 essage string is
2b620 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 managed interna
2b630 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 lly.** and must
2b640 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20 not be freed by
2b650 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 the application)
2b660 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 ^..**.** When th
2b670 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 e serialized [th
2b680 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 reading mode] is
2b690 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 in use, it migh
2b6a0 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 t be the.** case
2b6b0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 that a second e
2b6c0 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 rror occurs on a
2b6d0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 separate thread
2b6e0 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 in between.** t
2b6f0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 he time of the f
2b700 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 irst error and t
2b710 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 he call to these
2b720 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
2b730 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e When that happen
2b740 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 s, the second er
2b750 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f ror will be repo
2b760 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 rted since these
2b770 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 .** interfaces a
2b780 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 lways report the
2b790 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 most recent res
2b7a0 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a ult. To avoid.*
2b7b0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 * this, each thr
2b7c0 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 ead can obtain e
2b7d0 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 xclusive use of
2b7e0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
2b7f0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 nnection] D.** b
2b800 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 y invoking [sqli
2b810 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d te3_mutex_enter]
2b820 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 ([sqlite3_db_mut
2b830 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 ex](D)) before b
2b840 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 eginning.** to u
2b850 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e se D and invokin
2b860 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 g [sqlite3_mutex
2b870 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 _leave]([sqlite3
2b880 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 _db_mutex](D)) a
2b890 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c fter.** all call
2b8a0 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 s to the interfa
2b8b0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 ces listed here
2b8c0 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a are completed..*
2b8d0 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 *.** If an inter
2b8e0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 face fails with
2b8f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 SQLITE_MISUSE, t
2b900 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e hat means the in
2b910 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 terface.** was i
2b920 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 nvoked incorrect
2b930 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ly by the applic
2b940 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 ation. In that
2b950 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 case, the.** err
2b960 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 or code and mess
2b970 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e age may or may n
2b980 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e ot be set..*/.in
2b990 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 t sqlite3_errcod
2b9a0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a e(sqlite3 *db);.
2b9b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
2b9c0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c nded_errcode(sql
2b9d0 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 ite3 *db);.const
2b9e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 char *sqlite3_e
2b9f0 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b rrmsg(sqlite3*);
2ba00 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
2ba10 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 ite3_errmsg16(sq
2ba20 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 lite3*);.const c
2ba30 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 har *sqlite3_err
2ba40 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a str(int);../*.**
2ba50 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 CAPI3REF: Prepa
2ba60 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 red Statement Ob
2ba70 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ject.** KEYWORDS
2ba80 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 : {prepared stat
2ba90 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 ement} {prepared
2baa0 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a statements}.**.
2bab0 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f ** An instance o
2bac0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 f this object re
2bad0 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c presents a singl
2bae0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
2baf0 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e that.** has been
2bb00 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 compiled into b
2bb10 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 inary form and i
2bb20 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 s ready to be ev
2bb30 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 aluated..**.** T
2bb40 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c hink of each SQL
2bb50 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 statement as a
2bb60 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 separate compute
2bb70 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a r program. The.
2bb80 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 ** original SQL
2bb90 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 text is source c
2bba0 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 ode. A prepared
2bbb0 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 statement objec
2bbc0 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d t .** is the com
2bbd0 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 piled object cod
2bbe0 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 e. All SQL must
2bbf0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e be converted in
2bc00 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 to a.** prepared
2bc10 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 statement befor
2bc20 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e e it can be run.
2bc30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d .**.** The life-
2bc40 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 cycle of a prepa
2bc50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 red statement ob
2bc60 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 ject usually goe
2bc70 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a s like this:.**.
2bc80 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ol>.** <li>
2bc90 43 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61 Create the prepa
2bca0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 red statement ob
2bcb0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ject using [sqli
2bcc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2bcd0 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 ]..** <li> Bind
2bce0 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d values to [param
2bcf0 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 eters] using the
2bd00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
2bd10 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 ).** interf
2bd20 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 aces..** <li> Ru
2bd30 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c n the SQL by cal
2bd40 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 ling [sqlite3_st
2bd50 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 ep()] one or mor
2bd60 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e e times..** <li>
2bd70 20 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61 Reset the prepa
2bd80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 red statement us
2bd90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
2bda0 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 et()] then go ba
2bdb0 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 ck.** to st
2bdc0 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a ep 2. Do this z
2bdd0 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 ero or more time
2bde0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 s..** <li> Destr
2bdf0 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 oy the object us
2be00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
2be10 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f alize()]..** </o
2be20 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 l>.*/.typedef st
2be30 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d ruct sqlite3_stm
2be40 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a t sqlite3_stmt;.
2be50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2be60 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 Run-time Limits
2be70 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
2be80 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 te3.**.** ^(This
2be90 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 interface allow
2bea0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 s the size of va
2beb0 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 rious constructs
2bec0 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a to be limited.*
2bed0 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f * on a connectio
2bee0 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 n by connection
2bef0 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 basis. The firs
2bf00 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 t parameter is t
2bf10 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 he.** [database
2bf20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 connection] whos
2bf30 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 e limit is to be
2bf40 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e set or queried.
2bf50 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 The.** second
2bf60 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 parameter is one
2bf70 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 of the [limit c
2bf80 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 ategories] that
2bf90 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 define a.** clas
2bfa0 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 s of constructs
2bfb0 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 to be size limit
2bfc0 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 ed. The third p
2bfd0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a arameter is the.
2bfe0 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 ** new limit for
2bff0 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e that construct.
2c000 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 )^.**.** ^If the
2c010 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 new limit is a
2c020 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c negative number,
2c030 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e the limit is un
2c040 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f changed..** ^(Fo
2c050 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 r each limit cat
2c060 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d egory SQLITE_LIM
2c070 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 IT_<i>NAME</i> t
2c080 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c here is a .** [l
2c090 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 imits | hard upp
2c0a0 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 er bound].** set
2c0b0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 at compile-time
2c0c0 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 by a C preproce
2c0d0 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 ssor macro calle
2c0e0 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 d.** [limits | S
2c0f0 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d QLITE_MAX_<i>NAM
2c100 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 E</i>]..** (The
2c110 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 "_LIMIT_" in the
2c120 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 name is changed
2c130 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a to "_MAX_".))^.
2c140 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 ** ^Attempts to
2c150 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 increase a limit
2c160 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 above its hard
2c170 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a upper bound are.
2c180 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e ** silently trun
2c190 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 cated to the har
2c1a0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a d upper bound..*
2c1b0 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 *.** ^Regardless
2c1c0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
2c1d0 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 ot the limit was
2c1e0 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a changed, the .*
2c1f0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 * [sqlite3_limit
2c200 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 ()] interface re
2c210 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 turns the prior
2c220 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d value of the lim
2c230 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 it..** ^Hence, t
2c240 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 o find the curre
2c250 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 nt value of a li
2c260 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e mit without chan
2c270 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 ging it,.** simp
2c280 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 ly invoke this i
2c290 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 nterface with th
2c2a0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
2c2b0 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a r set to -1..**.
2c2c0 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 ** Run-time limi
2c2d0 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 ts are intended
2c2e0 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 for use in appli
2c2f0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e cations that man
2c300 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 age.** both thei
2c310 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 r own internal d
2c320 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f atabase and also
2c330 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 databases that
2c340 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a are controlled.*
2c350 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 * by untrusted e
2c360 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e xternal sources.
2c370 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 An example app
2c380 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 lication might b
2c390 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 e a.** web brows
2c3a0 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 er that has its
2c3b0 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f own databases fo
2c3c0 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 r storing histor
2c3d0 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 y and.** separat
2c3e0 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 e databases cont
2c3f0 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 rolled by JavaSc
2c400 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e ript application
2c410 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 s downloaded.**
2c420 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 off the Internet
2c430 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 . The internal
2c440 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 databases can be
2c450 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 given the.** la
2c460 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d rge, default lim
2c470 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 its. Databases
2c480 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 managed by exter
2c490 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a nal sources can.
2c4a0 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 ** be given much
2c4b0 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 smaller limits
2c4c0 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 designed to prev
2c4d0 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 ent a denial of
2c4e0 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 service.** attac
2c4f0 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d k. Developers m
2c500 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 ight also want t
2c510 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 o use the [sqlit
2c520 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
2c530 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 r()].** interfac
2c540 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e e to further con
2c550 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 trol untrusted S
2c560 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 QL. The size of
2c570 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
2c580 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 created by an u
2c590 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 ntrusted script
2c5a0 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 can be contained
2c5b0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d using the.** [m
2c5c0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b ax_page_count] [
2c5d0 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e PRAGMA]..**.** N
2c5e0 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 ew run-time limi
2c5f0 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 t categories may
2c600 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
2c610 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f ure releases..*/
2c620 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d .int sqlite3_lim
2c630 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 it(sqlite3*, int
2c640 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 id, int newVal)
2c650 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2c660 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 F: Run-Time Limi
2c670 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 t Categories.**
2c680 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 KEYWORDS: {limit
2c690 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d category} {*lim
2c6a0 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a it categories}.*
2c6b0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
2c6c0 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 ants define vari
2c6d0 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 ous performance
2c6e0 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 limits.** that c
2c6f0 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 an be lowered at
2c700 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 run-time using
2c710 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 [sqlite3_limit()
2c720 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 ]..** The synops
2c730 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e is of the meanin
2c740 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 gs of the variou
2c750 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 s limits is show
2c760 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 n below..** Addi
2c770 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 tional informati
2c780 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 on is available
2c790 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d at [limits | Lim
2c7a0 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a its in SQLite]..
2c7b0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b **.** <dl>.** [[
2c7c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e SQLITE_LIMIT_LEN
2c7d0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 GTH]] ^(<dt>SQLI
2c7e0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c TE_LIMIT_LENGTH<
2c7f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
2c800 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 maximum size of
2c810 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c any string or BL
2c820 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c OB or table row,
2c830 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e in bytes.<dd>)^
2c840 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
2c850 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 LIMIT_SQL_LENGTH
2c860 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
2c870 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 LIMIT_SQL_LENGTH
2c880 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
2c890 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 maximum length
2c8a0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d of an SQL statem
2c8b0 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f ent, in bytes.</
2c8c0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
2c8d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d LITE_LIMIT_COLUM
2c8e0 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 N]] ^(<dt>SQLITE
2c8f0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 _LIMIT_COLUMN</d
2c900 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
2c910 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
2c920 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 columns in a tab
2c930 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 le definition or
2c940 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c in the.** resul
2c950 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 t set of a [SELE
2c960 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d CT] or the maxim
2c970 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c um number of col
2c980 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 umns in an index
2c990 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 .** or in an ORD
2c9a0 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 ER BY or GROUP B
2c9b0 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e Y clause.</dd>)^
2c9c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
2c9d0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 LIMIT_EXPR_DEPTH
2c9e0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
2c9f0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 LIMIT_EXPR_DEPTH
2ca00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
2ca10 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f maximum depth o
2ca20 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 f the parse tree
2ca30 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 on any expressi
2ca40 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a on.</dd>)^.**.**
2ca50 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
2ca60 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d COMPOUND_SELECT]
2ca70 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
2ca80 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
2ca90 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LECT</dt>.** <dd
2caa0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
2cab0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 ber of terms in
2cac0 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 a compound SELEC
2cad0 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 T statement.</dd
2cae0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
2caf0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 TE_LIMIT_VDBE_OP
2cb00 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
2cb10 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 LIMIT_VDBE_OP</d
2cb20 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
2cb30 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
2cb40 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 instructions in
2cb50 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e a virtual machin
2cb60 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 e program.** use
2cb70 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 d to implement a
2cb80 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e n SQL statement.
2cb90 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 If [sqlite3_pr
2cba0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a epare_v2()] or.*
2cbb0 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 * the equivalent
2cbc0 20 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 tries to alloca
2cbd0 74 65 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 te space for mor
2cbe0 65 20 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 e than this many
2cbf0 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 opcodes.** in a
2cc00 20 73 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64 single prepared
2cc10 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 statement, an S
2cc20 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f QLITE_NOMEM erro
2cc30 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f r is returned.</
2cc40 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
2cc50 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
2cc60 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e ION_ARG]] ^(<dt>
2cc70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
2cc80 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a CTION_ARG</dt>.*
2cc90 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
2cca0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 m number of argu
2ccb0 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 ments on a funct
2ccc0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ion.</dd>)^.**.*
2ccd0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
2cce0 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 _ATTACHED]] ^(<d
2ccf0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 t>SQLITE_LIMIT_A
2cd00 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 TTACHED</dt>.**
2cd10 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
2cd20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 number of [ATTAC
2cd30 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 H | attached dat
2cd40 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a abases].)^</dd>.
2cd50 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
2cd60 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 IMIT_LIKE_PATTER
2cd70 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 N_LENGTH]].** ^(
2cd80 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
2cd90 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 _LIKE_PATTERN_LE
2cda0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
2cdb0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e >The maximum len
2cdc0 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 gth of the patte
2cdd0 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 rn argument to t
2cde0 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 he [LIKE] or.**
2cdf0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 [GLOB] operators
2ce00 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
2ce10 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 [SQLITE_LIMIT_VA
2ce20 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a RIABLE_NUMBER]].
2ce30 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ** ^(<dt>SQLITE_
2ce40 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
2ce50 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 UMBER</dt>.** <d
2ce60 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e d>The maximum in
2ce70 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e dex number of an
2ce80 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e y [parameter] in
2ce90 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
2cea0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c t.)^.**.** [[SQL
2ceb0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 ITE_LIMIT_TRIGGE
2cec0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e R_DEPTH]] ^(<dt>
2ced0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 SQLITE_LIMIT_TRI
2cee0 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a GGER_DEPTH</dt>.
2cef0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
2cf00 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 um depth of recu
2cf10 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 rsion for trigge
2cf20 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a rs.</dd>)^.**.**
2cf30 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
2cf40 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d WORKER_THREADS]]
2cf50 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
2cf60 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 MIT_WORKER_THREA
2cf70 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 DS</dt>.** <dd>T
2cf80 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
2cf90 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 r of auxiliary w
2cfa0 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 orker threads th
2cfb0 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b at a single.** [
2cfc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2cfd0 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f nt] may start.</
2cfe0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a dd>)^.** </dl>.*
2cff0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2d000 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 _LIMIT_LENGTH
2d010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2d020 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
2d030 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
2d040 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
2d050 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
2d060 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 TE_LIMIT_COLUMN
2d070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2d080 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
2d090 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 ITE_LIMIT_EXPR_D
2d0a0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 EPTH
2d0b0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
2d0c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f LITE_LIMIT_COMPO
2d0d0 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 UND_SELECT
2d0e0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 4.#define S
2d0f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 QLITE_LIMIT_VDBE
2d100 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 _OP
2d110 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 5.#define
2d120 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
2d130 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 CTION_ARG
2d140 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 6.#define
2d150 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 SQLITE_LIMIT_AT
2d160 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 TACHED
2d170 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 7.#defin
2d180 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c e SQLITE_LIMIT_L
2d190 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
2d1a0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 TH 8.#defi
2d1b0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
2d1c0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 VARIABLE_NUMBER
2d1d0 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 9.#def
2d1e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
2d1f0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 _TRIGGER_DEPTH
2d200 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 10.#de
2d210 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
2d220 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 T_WORKER_THREADS
2d230 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 11../
2d240 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 *.** CAPI3REF: P
2d250 72 65 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a 0a repare Flags.**.
2d260 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
2d270 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 ts define variou
2d280 73 20 66 6c 61 67 73 20 74 68 61 74 20 63 61 6e s flags that can
2d290 20 62 65 20 70 61 73 73 65 64 20 69 6e 74 6f 0a be passed into.
2d2a0 2a 2a 20 22 70 72 65 70 46 6c 61 67 73 22 20 70 ** "prepFlags" p
2d2b0 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 arameter of the
2d2c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2d2d0 5f 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 _v3()] and.** [s
2d2e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2d2f0 5f 76 33 28 29 5d 20 69 6e 74 65 72 66 61 63 65 _v3()] interface
2d300 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61 s..**.** New fla
2d310 67 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 gs may be added
2d320 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
2d330 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
2d340 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 .** <dl>.** [[SQ
2d350 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 LITE_PREPARE_PER
2d360 53 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e SISTENT]] ^(<dt>
2d370 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 SQLITE_PREPARE_P
2d380 45 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a ERSISTENT</dt>.*
2d390 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 * <dd>The SQLITE
2d3a0 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 _PREPARE_PERSIST
2d3b0 45 4e 54 20 66 6c 61 67 20 69 73 20 61 20 68 69 ENT flag is a hi
2d3c0 6e 74 20 74 6f 20 74 68 65 20 71 75 65 72 79 20 nt to the query
2d3d0 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74 20 planner.** that
2d3e0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 the prepared sta
2d3f0 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 72 tement will be r
2d400 65 74 61 69 6e 65 64 20 66 6f 72 20 61 20 6c 6f etained for a lo
2d410 6e 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20 70 ng time and.** p
2d420 72 6f 62 61 62 6c 79 20 72 65 75 73 65 64 20 6d robably reused m
2d430 61 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57 69 any times.)^ ^Wi
2d440 74 68 6f 75 74 20 74 68 69 73 20 66 6c 61 67 2c thout this flag,
2d450 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2d460 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b e_v3()].** and [
2d470 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2d480 36 5f 76 33 28 29 5d 20 61 73 73 75 6d 65 20 74 6_v3()] assume t
2d490 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 hat the prepared
2d4a0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 statement will
2d4b0 0a 2a 2a 20 62 65 20 75 73 65 64 20 6a 75 73 74 .** be used just
2d4c0 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73 74 once or at most
2d4d0 20 61 20 66 65 77 20 74 69 6d 65 73 20 61 6e 64 a few times and
2d4e0 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20 then destroyed
2d4f0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
2d500 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72 65 3_finalize()] re
2d510 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20 54 latively soon. T
2d520 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 he current imple
2d530 6d 65 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a 2a mentation acts.*
2d540 2a 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 62 * on this hint b
2d550 79 20 61 76 6f 69 64 69 6e 67 20 74 68 65 20 75 y avoiding the u
2d560 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64 65 se of [lookaside
2d570 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20 6e memory] so as n
2d580 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74 65 ot to.** deplete
2d590 20 74 68 65 20 6c 69 6d 69 74 65 64 20 73 74 6f the limited sto
2d5a0 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 re of lookaside
2d5b0 6d 65 6d 6f 72 79 2e 20 46 75 74 75 72 65 20 76 memory. Future v
2d5c0 65 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51 ersions of.** SQ
2d5d0 4c 69 74 65 20 6d 61 79 20 61 63 74 20 6f 6e 20 Lite may act on
2d5e0 74 68 69 73 20 68 69 6e 74 20 64 69 66 66 65 72 this hint differ
2d5f0 65 6e 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 ently..**.** [[S
2d600 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f QLITE_PREPARE_NO
2d610 52 4d 41 4c 49 5a 45 5d 5d 20 3c 64 74 3e 53 51 RMALIZE]] <dt>SQ
2d620 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 52 LITE_PREPARE_NOR
2d630 4d 41 4c 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c MALIZE</dt>.** <
2d640 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50 52 dd>The SQLITE_PR
2d650 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 20 EPARE_NORMALIZE
2d660 66 6c 61 67 20 69 73 20 61 20 6e 6f 2d 6f 70 2e flag is a no-op.
2d670 20 54 68 69 73 20 66 6c 61 67 20 75 73 65 64 0a This flag used.
2d680 2a 2a 20 74 6f 20 62 65 20 72 65 71 75 69 72 65 ** to be require
2d690 64 20 66 6f 72 20 61 6e 79 20 70 72 65 70 61 72 d for any prepar
2d6a0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 ed statement tha
2d6b0 74 20 77 61 6e 74 65 64 20 74 6f 20 75 73 65 20 t wanted to use
2d6c0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
2d6d0 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 29 normalized_sql()
2d6e0 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 48 6f ] interface. Ho
2d6f0 77 65 76 65 72 2c 20 74 68 65 0a 2a 2a 20 5b 73 wever, the.** [s
2d700 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 qlite3_normalize
2d710 64 5f 73 71 6c 28 29 5d 20 69 6e 74 65 72 66 61 d_sql()] interfa
2d720 63 65 20 69 73 20 6e 6f 77 20 61 76 61 69 6c 61 ce is now availa
2d730 62 6c 65 20 74 6f 20 61 6c 6c 0a 2a 2a 20 70 72 ble to all.** pr
2d740 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2d750 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 s, regardless of
2d760 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
2d770 74 68 65 79 20 75 73 65 20 74 68 69 73 0a 2a 2a they use this.**
2d780 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 flag..**.** [[S
2d790 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f QLITE_PREPARE_NO
2d7a0 5f 56 54 41 42 5d 5d 20 3c 64 74 3e 53 51 4c 49 _VTAB]] <dt>SQLI
2d7b0 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 5f 56 54 TE_PREPARE_NO_VT
2d7c0 41 42 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 AB</dt>.** <dd>T
2d7d0 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 he SQLITE_PREPAR
2d7e0 45 5f 4e 4f 5f 56 54 41 42 20 66 6c 61 67 20 63 E_NO_VTAB flag c
2d7f0 61 75 73 65 73 20 74 68 65 20 53 51 4c 20 63 6f auses the SQL co
2d800 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f 20 72 65 74 mpiler.** to ret
2d810 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 28 65 72 urn an error (er
2d820 72 6f 72 20 63 6f 64 65 20 53 51 4c 49 54 45 5f ror code SQLITE_
2d830 45 52 52 4f 52 29 20 69 66 20 74 68 65 20 73 74 ERROR) if the st
2d840 61 74 65 6d 65 6e 74 20 75 73 65 73 0a 2a 2a 20 atement uses.**
2d850 61 6e 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c any virtual tabl
2d860 65 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a es..** </dl>.*/.
2d870 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 #define SQLITE_P
2d880 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e REPARE_PERSISTEN
2d890 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 T 0
2d8a0 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 x01.#define SQLI
2d8b0 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 52 4d 41 TE_PREPARE_NORMA
2d8c0 4c 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 LIZE
2d8d0 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 0x02.#define
2d8e0 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e SQLITE_PREPARE_N
2d8f0 4f 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20 O_VTAB
2d900 20 20 20 20 20 20 20 30 78 30 34 0a 0a 2f 2a 0a 0x04../*.
2d910 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
2d920 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 piling An SQL St
2d930 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f atement.** KEYWO
2d940 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d RDS: {SQL statem
2d950 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a ent compiler}.**
2d960 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
2d970 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a .** CONSTRUCTOR:
2d980 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
2d990 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 .** To execute a
2d9a0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c n SQL statement,
2d9b0 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 it must first b
2d9c0 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 e compiled into
2d9d0 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 a byte-code.** p
2d9e0 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 rogram using one
2d9f0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
2da00 65 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65 es. Or, in othe
2da10 72 20 77 6f 72 64 73 2c 20 74 68 65 73 65 20 72 r words, these r
2da20 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63 outines.** are c
2da30 6f 6e 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20 onstructors for
2da40 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
2da50 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e atement] object.
2da60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66 65 .**.** The prefe
2da70 72 72 65 64 20 72 6f 75 74 69 6e 65 20 74 6f 20 rred routine to
2da80 75 73 65 20 69 73 20 5b 73 71 6c 69 74 65 33 5f use is [sqlite3_
2da90 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 20 20 prepare_v2()].
2daa0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f The.** [sqlite3_
2dab0 70 72 65 70 61 72 65 28 29 5d 20 69 6e 74 65 72 prepare()] inter
2dac0 66 61 63 65 20 69 73 20 6c 65 67 61 63 79 20 61 face is legacy a
2dad0 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f nd should be avo
2dae0 69 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 ided..** [sqlite
2daf0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 3_prepare_v3()]
2db00 68 61 73 20 61 6e 20 65 78 74 72 61 20 22 70 72 has an extra "pr
2db10 65 70 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20 epFlags" option
2db20 74 68 61 74 20 69 73 20 75 73 65 64 0a 2a 2a 20 that is used.**
2db30 66 6f 72 20 73 70 65 63 69 61 6c 20 70 75 72 70 for special purp
2db40 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 oses..**.** The
2db50 75 73 65 20 6f 66 20 74 68 65 20 55 54 46 2d 38 use of the UTF-8
2db60 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 70 interfaces is p
2db70 72 65 66 65 72 72 65 64 2c 20 61 73 20 53 51 4c referred, as SQL
2db80 69 74 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a ite currently.**
2db90 20 64 6f 65 73 20 61 6c 6c 20 70 61 72 73 69 6e does all parsin
2dba0 67 20 75 73 69 6e 67 20 55 54 46 2d 38 2e 20 20 g using UTF-8.
2dbb0 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 The UTF-16 inter
2dbc0 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 faces are provid
2dbd0 65 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65 ed.** as a conve
2dbe0 6e 69 65 6e 63 65 2e 20 20 54 68 65 20 55 54 46 nience. The UTF
2dbf0 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 77 -16 interfaces w
2dc00 6f 72 6b 20 62 79 20 63 6f 6e 76 65 72 74 69 6e ork by convertin
2dc10 67 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74 g the.** input t
2dc20 65 78 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20 ext into UTF-8,
2dc30 74 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68 then invoking th
2dc40 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
2dc50 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 2e UTF-8 interface.
2dc60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
2dc70 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c argument, "db",
2dc80 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 is a [database
2dc90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 connection] obta
2dca0 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 ined from a.** p
2dcb0 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 rior successful
2dcc0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2dcd0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
2dce0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 e3_open_v2()] or
2dcf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
2dd00 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 n16()]. The dat
2dd10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2dd20 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 must not have b
2dd30 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a een closed..**.*
2dd40 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 * The second arg
2dd50 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 ument, "zSql", i
2dd60 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 s the statement
2dd70 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 to be compiled,
2dd80 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 encoded.** as ei
2dd90 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 ther UTF-8 or UT
2dda0 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 F-16. The sqlit
2ddb0 65 33 5f 70 72 65 70 61 72 65 28 29 2c 20 73 71 e3_prepare(), sq
2ddc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2ddd0 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 (),.** and sqlit
2dde0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 0a e3_prepare_v3().
2ddf0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 ** interfaces us
2de00 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c e UTF-8, and sql
2de10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
2de20 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 , sqlite3_prepar
2de30 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 e16_v2(),.** and
2de40 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
2de50 31 36 5f 76 33 28 29 20 75 73 65 20 55 54 46 2d 16_v3() use UTF-
2de60 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 16..**.** ^If th
2de70 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 e nByte argument
2de80 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
2de90 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 en zSql is read
2dea0 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 up to the.** fir
2deb0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 st zero terminat
2dec0 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 or. ^If nByte is
2ded0 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 positive, then
2dee0 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d it is the.** num
2def0 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 ber of bytes rea
2df00 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 d from zSql. ^I
2df10 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c f nByte is zero,
2df20 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 then no prepare
2df30 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 d.** statement i
2df40 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 s generated..**
2df50 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e If the caller kn
2df60 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70 ows that the sup
2df70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 plied string is
2df80 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 nul-terminated,
2df90 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 then.** there is
2dfa0 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d a small perform
2dfb0 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 ance advantage t
2dfc0 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 o passing an nBy
2dfd0 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 te parameter tha
2dfe0 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 t.** is the numb
2dff0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
2e000 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 he input string
2e010 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e <i>including</i>
2e020 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d .** the nul-term
2e030 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 inator..**.** ^I
2e040 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 f pzTail is not
2e050 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 NULL then *pzTai
2e060 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 l is made to poi
2e070 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 nt to the first
2e080 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 byte.** past the
2e090 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 end of the firs
2e0a0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 t SQL statement
2e0b0 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 in zSql. These
2e0c0 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a routines only.**
2e0d0 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 compile the fir
2e0e0 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 st statement in
2e0f0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c zSql, so *pzTail
2e100 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e is left pointin
2e110 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d g to.** what rem
2e120 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e ains uncompiled.
2e130 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 .**.** ^*ppStmt
2e140 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 is left pointing
2e150 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b to a compiled [
2e160 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2e170 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a nt] that can be.
2e180 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e ** executed usin
2e190 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
2e1a0 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 )]. ^If there i
2e1b0 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 s an error, *ppS
2e1c0 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f tmt is set.** to
2e1d0 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 NULL. ^If the
2e1e0 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 input text conta
2e1f0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 ins no SQL (if t
2e200 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 he input is an e
2e210 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f mpty.** string o
2e220 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 r a comment) the
2e230 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 n *ppStmt is set
2e240 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 to NULL..** The
2e250 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 calling procedu
2e260 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c re is responsibl
2e270 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 e for deleting t
2e280 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 he compiled.** S
2e290 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 QL statement usi
2e2a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
2e2b0 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 lize()] after it
2e2c0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
2e2d0 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 th it..** ppStmt
2e2e0 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c may not be NULL
2e2f0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 ..**.** ^On succ
2e300 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ess, the sqlite3
2e310 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c _prepare() famil
2e320 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 y of routines re
2e330 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
2e340 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 ;.** otherwise a
2e350 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
2e360 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
2e370 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 * The sqlite3_pr
2e380 65 70 61 72 65 5f 76 32 28 29 2c 20 73 71 6c 69 epare_v2(), sqli
2e390 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 te3_prepare_v3()
2e3a0 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 , sqlite3_prepar
2e3b0 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 e16_v2(),.** and
2e3c0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
2e3d0 31 36 5f 76 33 28 29 20 69 6e 74 65 72 66 61 63 16_v3() interfac
2e3e0 65 73 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64 es are recommend
2e3f0 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 ed for all new p
2e400 72 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20 rograms..** The
2e410 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 older interfaces
2e420 20 28 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 (sqlite3_prepar
2e430 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f e() and sqlite3_
2e440 70 72 65 70 61 72 65 31 36 28 29 29 0a 2a 2a 20 prepare16()).**
2e450 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 are retained for
2e460 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
2e470 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 tibility, but th
2e480 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f eir use is disco
2e490 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 uraged..** ^In t
2e4a0 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 he "vX" interfac
2e4b0 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 es, the prepared
2e4c0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 statement.** th
2e4d0 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 at is returned (
2e4e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
2e4f0 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 t] object) conta
2e500 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 ins a copy of th
2e510 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 e.** original SQ
2e520 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 L text. This cau
2e530 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ses the [sqlite3
2e540 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 _step()] interfa
2e550 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 ce to.** behave
2e560 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 differently in t
2e570 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a hree ways:.**.**
2e580 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a <ol>.** <li>.**
2e590 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 ^If the databas
2e5a0 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 e schema changes
2e5b0 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 , instead of ret
2e5c0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 urning [SQLITE_S
2e5d0 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 CHEMA] as it.**
2e5e0 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 always used to d
2e5f0 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 o, [sqlite3_step
2e600 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 ()] will automat
2e610 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 ically recompile
2e620 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 the SQL.** stat
2e630 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f ement and try to
2e640 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 run it again. A
2e650 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 s many as [SQLIT
2e660 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 E_MAX_SCHEMA_RET
2e670 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 RY].** retries w
2e680 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 ill occur before
2e690 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
2e6a0 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 gives up and ret
2e6b0 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a urns an error..*
2e6c0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c * </li>.**.** <l
2e6d0 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 i>.** ^When an e
2e6e0 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 rror occurs, [sq
2e6f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
2e700 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 ll return one of
2e710 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a the detailed.**
2e720 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f [error codes] o
2e730 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f r [extended erro
2e740 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 r codes]. ^The
2e750 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 legacy behavior
2e760 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c was that.** [sql
2e770 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 ite3_step()] wou
2e780 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 ld only return a
2e790 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 generic [SQLITE
2e7a0 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 _ERROR] result c
2e7b0 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 ode.** and the a
2e7c0 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 pplication would
2e7d0 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 have to make a
2e7e0 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b second call to [
2e7f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2e800 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 .** in order to
2e810 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 find the underly
2e820 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 ing cause of the
2e830 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 problem. With t
2e840 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a he "v2" prepare.
2e850 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 ** interfaces, t
2e860 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 he underlying re
2e870 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 ason for the err
2e880 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 or is returned i
2e890 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c mmediately..** <
2e8a0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a /li>.**.** <li>.
2e8b0 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 ** ^If the speci
2e8c0 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 fic value bound
2e8d0 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 to [parameter |
2e8e0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 host parameter]
2e8f0 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 in the .** WHERE
2e900 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e clause might in
2e910 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 fluence the choi
2e920 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e ce of query plan
2e930 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 for a statement
2e940 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 ,.** then the st
2e950 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 atement will be
2e960 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 automatically re
2e970 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 compiled, as if
2e980 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a there had been .
2e990 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e ** a schema chan
2e9a0 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 ge, on the first
2e9b0 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 [sqlite3_step(
2e9c0 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e )] call followin
2e9d0 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 g any change.**
2e9e0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
2e9f0 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 bind_text | bind
2ea00 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 ings] of that [p
2ea10 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e arameter]. .** ^
2ea20 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c The specific val
2ea30 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 ue of WHERE-clau
2ea40 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d se [parameter] m
2ea50 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 ight influence t
2ea60 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 he .** choice of
2ea70 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 query plan if t
2ea80 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 he parameter is
2ea90 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 the left-hand si
2eaa0 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a de of a [LIKE].*
2eab0 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 * or [GLOB] oper
2eac0 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 ator or if the p
2ead0 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 arameter is comp
2eae0 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 ared to an index
2eaf0 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 ed column.** and
2eb00 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 the [SQLITE_ENA
2eb10 42 4c 45 5f 53 54 41 54 34 5d 20 63 6f 6d 70 69 BLE_STAT4] compi
2eb20 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 le-time option i
2eb30 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f s enabled..** </
2eb40 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a li>.** </ol>.**.
2eb50 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70 ** <p>^sqlite3_p
2eb60 72 65 70 61 72 65 5f 76 33 28 29 20 64 69 66 66 repare_v3() diff
2eb70 65 72 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ers from sqlite3
2eb80 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 6f 6e _prepare_v2() on
2eb90 6c 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 ly in having.**
2eba0 74 68 65 20 65 78 74 72 61 20 70 72 65 70 46 6c the extra prepFl
2ebb0 61 67 73 20 70 61 72 61 6d 65 74 65 72 2c 20 77 ags parameter, w
2ebc0 68 69 63 68 20 69 73 20 61 20 62 69 74 20 61 72 hich is a bit ar
2ebd0 72 61 79 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f ray consisting o
2ebe0 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 f zero or.** mor
2ebf0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 e of the [SQLITE
2ec00 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 _PREPARE_PERSIST
2ec10 45 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45 50 41 ENT|SQLITE_PREPA
2ec20 52 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54 RE_*] flags. ^T
2ec30 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 he.** sqlite3_pr
2ec40 65 70 61 72 65 5f 76 32 28 29 20 69 6e 74 65 72 epare_v2() inter
2ec50 66 61 63 65 20 77 6f 72 6b 73 20 65 78 61 63 74 face works exact
2ec60 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a ly the same as.*
2ec70 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 * sqlite3_prepar
2ec80 65 5f 76 33 28 29 20 77 69 74 68 20 61 20 7a 65 e_v3() with a ze
2ec90 72 6f 20 70 72 65 70 46 6c 61 67 73 20 70 61 72 ro prepFlags par
2eca0 61 6d 65 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 ameter..*/.int s
2ecb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a qlite3_prepare(.
2ecc0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
2ecd0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
2ece0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
2ecf0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
2ed00 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
2ed10 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
2ed20 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 8 encoded */. i
2ed30 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
2ed40 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
2ed50 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
2ed60 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
2ed70 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
2ed80 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
2ed90 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
2eda0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
2edb0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
2edc0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
2edd0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
2ede0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e of zSql */.);.in
2edf0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
2ee00 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 e_v2(. sqlite3
2ee10 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
2ee20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
2ee30 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
2ee40 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 ar *zSql,
2ee50 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
2ee60 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 , UTF-8 encoded
2ee70 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 */. int nByte,
2ee80 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
2ee90 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f Maximum length o
2eea0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e f zSql in bytes.
2eeb0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 */. sqlite3_st
2eec0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a mt **ppStmt, /*
2eed0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 OUT: Statement
2eee0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
2eef0 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 t char **pzTail
2ef00 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e /* OUT: Poin
2ef10 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f ter to unused po
2ef20 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f rtion of zSql */
2ef30 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
2ef40 70 72 65 70 61 72 65 5f 76 33 28 0a 20 20 73 71 prepare_v3(. sq
2ef50 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
2ef60 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
2ef70 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
2ef80 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 nst char *zSql,
2ef90 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
2efa0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e tement, UTF-8 en
2efb0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
2efc0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
2efd0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
2efe0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
2eff0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 bytes. */. unsi
2f000 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61 gned int prepFla
2f010 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d gs, /* Zero or m
2f020 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 ore SQLITE_PREPA
2f030 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 RE_ flags */. s
2f040 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
2f050 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
2f060 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
2f070 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
2f080 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
2f090 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
2f0a0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
2f0b0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 f zSql */.);.int
2f0c0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
2f0d0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 16(. sqlite3 *d
2f0e0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
2f0f0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
2f100 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
2f110 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
2f120 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
2f130 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a UTF-16 encoded *
2f140 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
2f150 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
2f160 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
2f170 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
2f180 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
2f190 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
2f1a0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
2f1b0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
2f1c0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 void **pzTail
2f1d0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
2f1e0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
2f1f0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
2f200 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
2f210 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 repare16_v2(. s
2f220 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
2f230 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
2f240 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
2f250 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c onst void *zSql,
2f260 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
2f270 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 atement, UTF-16
2f280 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
2f290 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
2f2a0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
2f2b0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
2f2c0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 n bytes. */. sq
2f2d0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
2f2e0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
2f2f0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
2f300 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
2f310 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
2f320 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
2f330 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
2f340 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 zSql */.);.int
2f350 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2f360 36 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 6_v3(. sqlite3
2f370 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
2f380 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
2f390 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
2f3a0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 id *zSql,
2f3b0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
2f3c0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 , UTF-16 encoded
2f3d0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
2f3e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2f3f0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
2f400 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
2f410 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 . */. unsigned
2f420 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f int prepFlags, /
2f430 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 * Zero or more S
2f440 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 QLITE_PREPARE_ f
2f450 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 lags */. sqlite
2f460 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
2f470 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
2f480 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
2f490 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 const void **pzT
2f4a0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
2f4b0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
2f4c0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
2f4d0 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 l */.);../*.** C
2f4e0 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 API3REF: Retriev
2f4f0 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 ing Statement SQ
2f500 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c L.** METHOD: sql
2f510 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
2f520 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c ^The sqlite3_sql
2f530 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (P) interface re
2f540 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
2f550 74 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 to a copy of the
2f560 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 UTF-8.** SQL te
2f570 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 xt used to creat
2f580 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2f590 65 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 ement] P if P wa
2f5a0 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 s.** created by
2f5b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2f5c0 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v2()], [sqlite3
2f5d0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a _prepare_v3()],.
2f5e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
2f5f0 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 are16_v2()], or
2f600 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2f610 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68 16_v3()]..** ^Th
2f620 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 e sqlite3_expand
2f630 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 ed_sql(P) interf
2f640 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
2f650 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 inter to a UTF-8
2f660 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 .** string conta
2f670 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65 ining the SQL te
2f680 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73 xt of prepared s
2f690 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a tatement P with.
2f6a0 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 ** [bound parame
2f6b0 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a ters] expanded..
2f6c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2f6d0 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 50 normalized_sql(P
2f6e0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
2f6f0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
2f700 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 a UTF-8.** stri
2f710 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 ng containing th
2f720 65 20 6e 6f 72 6d 61 6c 69 7a 65 64 20 53 51 4c e normalized SQL
2f730 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72 65 text of prepare
2f740 64 20 73 74 61 74 65 6d 65 6e 74 20 50 2e 20 20 d statement P.
2f750 54 68 65 0a 2a 2a 20 73 65 6d 61 6e 74 69 63 73 The.** semantics
2f760 20 75 73 65 64 20 74 6f 20 6e 6f 72 6d 61 6c 69 used to normali
2f770 7a 65 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65 ze a SQL stateme
2f780 6e 74 20 61 72 65 20 75 6e 73 70 65 63 69 66 69 nt are unspecifi
2f790 65 64 20 61 6e 64 20 73 75 62 6a 65 63 74 0a 2a ed and subject.*
2f7a0 2a 20 74 6f 20 63 68 61 6e 67 65 2e 20 20 41 74 * to change. At
2f7b0 20 61 20 6d 69 6e 69 6d 75 6d 2c 20 6c 69 74 65 a minimum, lite
2f7c0 72 61 6c 20 76 61 6c 75 65 73 20 77 69 6c 6c 20 ral values will
2f7d0 62 65 20 72 65 70 6c 61 63 65 64 20 77 69 74 68 be replaced with
2f7e0 20 73 75 69 74 61 62 6c 65 0a 2a 2a 20 70 6c 61 suitable.** pla
2f7f0 63 65 68 6f 6c 64 65 72 73 2e 0a 2a 2a 0a 2a 2a ceholders..**.**
2f800 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ^(For example,
2f810 69 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 if a prepared st
2f820 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 atement is creat
2f830 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c ed using the SQL
2f840 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 .** text "SELECT
2f850 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 $abc,:xyz" and
2f860 69 66 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 if parameter $ab
2f870 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e c is bound to in
2f880 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e teger 2345.** an
2f890 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a d parameter :xyz
2f8a0 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 is unbound, the
2f8b0 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 n sqlite3_sql()
2f8c0 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 will return.** t
2f8d0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 he original stri
2f8e0 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 ng, "SELECT $abc
2f8f0 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 ,:xyz" but sqlit
2f900 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 e3_expanded_sql(
2f910 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e ).** will return
2f920 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 "SELECT 2345,NU
2f930 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 LL".)^.**.** ^Th
2f940 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 e sqlite3_expand
2f950 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 ed_sql() interfa
2f960 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 ce returns NULL
2f970 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 if insufficient
2f980 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 memory.** is ava
2f990 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 ilable to hold t
2f9a0 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 he result, or if
2f9b0 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c the result woul
2f9c0 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 d exceed the.**
2f9d0 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 the maximum stri
2f9e0 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d ng length determ
2f9f0 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c ined by the [SQL
2fa00 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 ITE_LIMIT_LENGTH
2fa10 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 ]..**.** ^The [S
2fa20 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 QLITE_TRACE_SIZE
2fa30 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d _LIMIT] compile-
2fa40 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 time option limi
2fa50 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a ts the size of.*
2fa60 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 * bound paramete
2fa70 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e r expansions. ^
2fa80 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 The [SQLITE_OMIT
2fa90 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d _TRACE] compile-
2faa0 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 time.** option c
2fab0 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 auses sqlite3_ex
2fac0 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 panded_sql() to
2fad0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 always return NU
2fae0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 LL..**.** ^The s
2faf0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 trings returned
2fb00 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 by sqlite3_sql(P
2fb10 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6e 6f ) and sqlite3_no
2fb20 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 50 29 0a rmalized_sql(P).
2fb30 2a 2a 20 61 72 65 20 6d 61 6e 61 67 65 64 20 62 ** are managed b
2fb40 79 20 53 51 4c 69 74 65 20 61 6e 64 20 61 72 65 y SQLite and are
2fb50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 automatically f
2fb60 72 65 65 64 20 77 68 65 6e 20 74 68 65 20 70 72 reed when the pr
2fb70 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d epared.** statem
2fb80 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 ent is finalized
2fb90 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 ..** ^The string
2fba0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
2fbb0 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 ite3_expanded_sq
2fbc0 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 l(P), on the oth
2fbd0 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f er hand,.** is o
2fbe0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
2fbf0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
2fc00 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65 65 and must be free
2fc10 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 by the applicat
2fc20 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e ion.** by passin
2fc30 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 g it to [sqlite3
2fc40 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e _free()]..*/.con
2fc50 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
2fc60 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d _sql(sqlite3_stm
2fc70 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20 t *pStmt);.char
2fc80 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 *sqlite3_expande
2fc90 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 d_sql(sqlite3_st
2fca0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 6f 6e 73 mt *pStmt);.cons
2fcb0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
2fcc0 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 73 normalized_sql(s
2fcd0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
2fce0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
2fcf0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 3REF: Determine
2fd00 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d If An SQL Statem
2fd10 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 ent Writes The D
2fd20 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f atabase.** METHO
2fd30 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
2fd40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2fd50 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
2fd60 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (X) interface re
2fd70 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d turns true (non-
2fd80 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 zero) if.** and
2fd90 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 only if the [pre
2fda0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2fdb0 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 X makes no dire
2fdc0 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a ct changes to.**
2fdd0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
2fde0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
2fdf0 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 e..**.** Note th
2fe00 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d at [application-
2fe10 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2fe20 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 tions] or.** [vi
2fe30 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 rtual tables] mi
2fe40 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 ght change the d
2fe50 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 atabase indirect
2fe60 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 ly as a side eff
2fe70 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 ect. .** ^(For
2fe80 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 example, if an a
2fe90 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
2fea0 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 es a function "e
2feb0 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 val()" that .**
2fec0 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 calls [sqlite3_e
2fed0 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 xec()], then the
2fee0 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 following SQL s
2fef0 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a tatement would.*
2ff00 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 * change the dat
2ff10 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 abase file throu
2ff20 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a gh side-effects:
2ff30 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
2ff40 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 te><pre>.** S
2ff50 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 ELECT eval('DELE
2ff60 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f TE FROM t1') FRO
2ff70 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c M t2;.** </pre><
2ff80 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
2ff90 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 ** But because t
2ffa0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 he [SELECT] stat
2ffb0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 ement does not c
2ffc0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 hange the databa
2ffd0 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 se file.** direc
2ffe0 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d tly, sqlite3_stm
2fff0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 t_readonly() wou
30000 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 ld still return
30010 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 true.)^.**.** ^T
30020 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 ransaction contr
30030 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 ol statements su
30040 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b ch as [BEGIN], [
30050 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 COMMIT], [ROLLBA
30060 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 CK],.** [SAVEPOI
30070 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 NT], and [RELEAS
30080 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 E] cause sqlite3
30090 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 _stmt_readonly()
300a0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c to return true,
300b0 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 .** since the st
300c0 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c atements themsel
300d0 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 ves do not actua
300e0 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 lly modify the d
300f0 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 atabase but.** r
30100 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 ather they contr
30110 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 ol the timing of
30120 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 when other stat
30130 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 ements modify th
30140 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 e .** database.
30150 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 ^The [ATTACH] a
30160 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 nd [DETACH] stat
30170 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 ements also caus
30180 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d e.** sqlite3_stm
30190 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 t_readonly() to
301a0 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 return true sinc
301b0 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 e, while those s
301c0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 tatements.** cha
301d0 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 nge the configur
301e0 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 ation of a datab
301f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 ase connection,
30200 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 they do not make
30210 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 .** changes to
30220 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
30230 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
30240 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 s on disk..** ^T
30250 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f he sqlite3_stmt_
30260 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 readonly() inter
30270 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 face returns tru
30280 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 e for [BEGIN] si
30290 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d nce.** [BEGIN] m
302a0 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72 erely sets inter
302b0 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74 nal flags, but t
302c0 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 he [BEGIN|BEGIN
302d0 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a IMMEDIATE] and.*
302e0 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 * [BEGIN|BEGIN E
302f0 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e XCLUSIVE] comman
30300 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20 ds do touch the
30310 64 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a database and so.
30320 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f ** sqlite3_stmt_
30330 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 readonly() retur
30340 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f ns false for tho
30350 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a se commands..*/.
30360 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 int sqlite3_stmt
30370 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 _readonly(sqlite
30380 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
30390 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
303a0 20 51 75 65 72 79 20 54 68 65 20 45 58 50 4c 41 Query The EXPLA
303b0 49 4e 20 53 65 74 74 69 6e 67 20 46 6f 72 20 41 IN Setting For A
303c0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
303d0 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ent.** METHOD: s
303e0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
303f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 * ^The sqlite3_s
30400 74 6d 74 5f 69 73 65 78 70 6c 61 69 6e 28 53 29 tmt_isexplain(S)
30410 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
30420 6e 73 20 31 20 69 66 20 74 68 65 0a 2a 2a 20 70 ns 1 if the.** p
30430 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
30440 74 20 53 20 69 73 20 61 6e 20 45 58 50 4c 41 49 t S is an EXPLAI
30450 4e 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 20 N statement, or
30460 32 20 69 66 20 74 68 65 0a 2a 2a 20 73 74 61 74 2 if the.** stat
30470 65 6d 65 6e 74 20 53 20 69 73 20 61 6e 20 45 58 ement S is an EX
30480 50 4c 41 49 4e 20 51 55 45 52 59 20 50 4c 41 4e PLAIN QUERY PLAN
30490 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
304a0 33 5f 73 74 6d 74 5f 69 73 65 78 70 6c 61 69 6e 3_stmt_isexplain
304b0 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (S) interface re
304c0 74 75 72 6e 73 20 30 20 69 66 20 53 20 69 73 0a turns 0 if S is.
304d0 2a 2a 20 61 6e 20 6f 72 64 69 6e 61 72 79 20 73 ** an ordinary s
304e0 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 20 4e 55 tatement or a NU
304f0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 LL pointer..*/.i
30500 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f nt sqlite3_stmt_
30510 69 73 65 78 70 6c 61 69 6e 28 73 71 6c 69 74 65 isexplain(sqlite
30520 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
30530 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
30540 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 Determine If A
30550 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
30560 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 nt Has Been Rese
30570 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
30580 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
30590 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d ^The sqlite3_stm
305a0 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 t_busy(S) interf
305b0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 ace returns true
305c0 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 (non-zero) if t
305d0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
305e0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 statement] S has
305f0 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 been stepped at
30600 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e least once usin
30610 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 g .** [sqlite3_s
30620 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 tep(S)] but has
30630 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 neither run to c
30640 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 ompletion (retur
30650 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 ned.** [SQLITE_D
30660 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 ONE] from [sqlit
30670 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 e3_step(S)]) nor
30680 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 .** been reset u
30690 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 sing [sqlite3_re
306a0 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 set(S)]. ^The s
306b0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 qlite3_stmt_busy
306c0 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 (S).** interface
306d0 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 returns false i
306e0 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f f S is a NULL po
306f0 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 inter. If S is
30700 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 not a .** NULL p
30710 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f ointer and is no
30720 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 t a pointer to a
30730 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 valid [prepared
30740 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f statement].** o
30750 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 bject, then the
30760 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 behavior is unde
30770 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
30780 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a ly undesirable..
30790 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
307a0 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 face can be used
307b0 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 in combination
307c0 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 [sqlite3_next_st
307d0 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 mt()].** to loca
307e0 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 te all prepared
307f0 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 statements assoc
30800 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 iated with a dat
30810 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 abase .** connec
30820 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e tion that are in
30830 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 need of being r
30840 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 eset. This can
30850 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 be used,.** for
30860 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 example, in diag
30870 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 nostic routines
30880 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 to search for pr
30890 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 epared .** state
308a0 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 ments that are h
308b0 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 olding a transac
308c0 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e tion open..*/.in
308d0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 t sqlite3_stmt_b
308e0 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 usy(sqlite3_stmt
308f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
30900 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 REF: Dynamically
30910 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a Typed Value Obj
30920 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ect.** KEYWORDS:
30930 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 {protected sqli
30940 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 te3_value} {unpr
30950 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
30960 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c value}.**.** SQL
30970 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c ite uses the sql
30980 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
30990 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 t to represent a
309a0 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 ll values.** tha
309b0 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 t can be stored
309c0 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 in a database ta
309d0 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 ble. SQLite uses
309e0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a dynamic typing.
309f0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 ** for the value
30a00 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 s it stores. ^V
30a10 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 alues stored in
30a20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
30a30 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 jects.** can be
30a40 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 integers, floati
30a50 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c ng point values,
30a60 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c strings, BLOBs,
30a70 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 or NULL..**.**
30a80 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 An sqlite3_value
30a90 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 object may be e
30aa0 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 ither "protected
30ab0 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 " or "unprotecte
30ac0 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 d"..** Some inte
30ad0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 rfaces require a
30ae0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 protected sqlit
30af0 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 e3_value. Other
30b00 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 interfaces.** w
30b10 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 ill accept eithe
30b20 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 r a protected or
30b30 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 an unprotected
30b40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a sqlite3_value..*
30b50 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 * Every interfac
30b60 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 e that accepts s
30b70 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 qlite3_value arg
30b80 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 uments specifies
30b90 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e .** whether or n
30ba0 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 ot it requires a
30bb0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 protected sqlit
30bc0 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a e3_value. The.*
30bd0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 * [sqlite3_value
30be0 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 _dup()] interfac
30bf0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
30c00 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 construct a new
30c10 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 .** protected s
30c20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f qlite3_value fro
30c30 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 m an unprotected
30c40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a sqlite3_value..
30c50 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 **.** The terms
30c60 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 "protected" and
30c70 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 "unprotected" re
30c80 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f fer to whether o
30c90 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 r not.** a mutex
30ca0 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e is held. An in
30cb0 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 ternal mutex is
30cc0 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 held for a prote
30cd0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
30ce0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 value object but
30cf0 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c no mutex is hel
30d00 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 d for an unprote
30d10 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
30d20 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 value object. I
30d30 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
30d40 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c iled to be singl
30d50 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 e-threaded.** (w
30d60 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 ith [SQLITE_THRE
30d70 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 ADSAFE=0] and wi
30d80 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 th [sqlite3_thre
30d90 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e adsafe()] return
30da0 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 ing 0).** or if
30db0 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e SQLite is run in
30dc0 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 one of reduced
30dd0 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 mutex modes .**
30de0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
30df0 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 INGLETHREAD] or
30e00 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
30e10 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 ULTITHREAD].** t
30e20 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 hen there is no
30e30 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 distinction betw
30e40 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e een protected an
30e50 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a d unprotected.**
30e60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
30e70 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 bjects and they
30e80 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 can be used inte
30e90 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f rchangeably. Ho
30ea0 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 wever,.** for ma
30eb0 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 ximum code porta
30ec0 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 bility it is rec
30ed0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 ommended that ap
30ee0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 plications.** st
30ef0 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 ill make the dis
30f00 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e tinction between
30f10 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 protected and u
30f20 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 nprotected.** sq
30f30 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
30f40 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f cts even when no
30f50 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 t strictly requi
30f60 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 red..**.** ^The
30f70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
30f80 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 jects that are p
30f90 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 assed as paramet
30fa0 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 ers into the.**
30fb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
30fc0 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 f [application-d
30fd0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
30fe0 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 ions] are protec
30ff0 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ted..** ^The sql
31000 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
31010 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a t returned by.**
31020 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
31030 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 _value()] is unp
31040 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 rotected..** Unp
31050 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
31060 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d _value objects m
31070 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 ay only be used
31080 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 as arguments.**
31090 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 to [sqlite3_resu
310a0 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73 71 lt_value()], [sq
310b0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 lite3_bind_value
310c0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
310d0 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 ite3_value_dup()
310e0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 ]..** The [sqlit
310f0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 e3_value_blob |
31100 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 sqlite3_value_ty
31110 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a pe()] family of.
31120 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 ** interfaces re
31130 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 quire protected
31140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
31150 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 jects..*/.typede
31160 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
31170 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f 76 _value sqlite3_v
31180 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 alue;../*.** CAP
31190 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 I3REF: SQL Funct
311a0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 ion Context Obje
311b0 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e ct.**.** The con
311c0 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e text in which an
311d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 SQL function ex
311e0 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 ecutes is stored
311f0 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 in an.** sqlite
31200 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 3_context object
31210 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f . ^A pointer to
31220 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 an sqlite3_cont
31230 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 ext object.** is
31240 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 always first pa
31250 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c rameter to [appl
31260 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
31270 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a SQL functions]..
31280 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
31290 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
312a0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
312b0 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 tation will pass
312c0 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 this.** pointer
312d0 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 through into ca
312e0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
312f0 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c result_int | sql
31300 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a ite3_result()],.
31310 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 ** [sqlite3_aggr
31320 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d egate_context()]
31330 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f , [sqlite3_user_
31340 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c data()],.** [sql
31350 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f ite3_context_db_
31360 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 handle()], [sqli
31370 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
31380 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 )],.** and/or [s
31390 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
313a0 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 ta()]..*/.typede
313b0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
313c0 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 _context sqlite3
313d0 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a _context;../*.**
313e0 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 CAPI3REF: Bindi
313f0 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 ng Values To Pre
31400 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 pared Statements
31410 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 .** KEYWORDS: {h
31420 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b ost parameter} {
31430 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d host parameters}
31440 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
31450 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 name}.** KEYWOR
31460 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 DS: {SQL paramet
31470 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 er} {SQL paramet
31480 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 ers} {parameter
31490 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 binding}.** METH
314a0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
314b0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 .**.** ^(In the
314c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 SQL statement te
314d0 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c xt input to [sql
314e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
314f0 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 )] and its varia
31500 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 nts,.** literals
31510 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 may be replaced
31520 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 by a [parameter
31530 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f ] that matches o
31540 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a ne of following.
31550 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a ** templates:.**
31560 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
31570 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e ?.** <li> ?NN
31580 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a N.** <li> :VVV.
31590 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a ** <li> @VVV.**
315a0 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c <li> $VVV.** <
315b0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 /ul>.**.** In th
315c0 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 e templates abov
315d0 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 e, NNN represent
315e0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 s an integer lit
315f0 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 eral,.** and VVV
31600 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 represents an a
31610 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e lphanumeric iden
31620 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 tifier.)^ ^The
31630 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a values of these.
31640 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 ** parameters (a
31650 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 lso called "host
31660 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 parameter names
31670 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 " or "SQL parame
31680 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 ters").** can be
31690 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 set using the s
316a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
316b0 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 routines defined
316c0 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 here..**.** ^Th
316d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
316e0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
316f0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
31700 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 s is always.** a
31710 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
31720 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f [sqlite3_stmt] o
31730 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 bject returned f
31740 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f rom.** [sqlite3_
31750 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
31760 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a its variants..*
31770 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 *.** ^The second
31780 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
31790 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 index of the SQ
317a0 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 L parameter to b
317b0 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c e set..** ^The l
317c0 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 eftmost SQL para
317d0 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 meter has an ind
317e0 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 ex of 1. ^When
317f0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a the same named.*
31800 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 * SQL parameter
31810 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 is used more tha
31820 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 n once, second a
31830 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a nd subsequent.**
31840 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 occurrences hav
31850 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 e the same index
31860 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 as the first oc
31870 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 currence..** ^Th
31880 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 e index for name
31890 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e d parameters can
318a0 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 be looked up us
318b0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
318c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
318d0 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 er_index()] API
318e0 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 if desired. ^Th
318f0 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 e index.** for "
31900 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 ?NNN" parameters
31910 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
31920 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e NNN..** ^The NN
31930 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 N value must be
31940 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 between 1 and th
31950 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 e [sqlite3_limit
31960 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ()].** parameter
31970 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 [SQLITE_LIMIT_V
31980 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 ARIABLE_NUMBER]
31990 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 (default value:
319a0 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 999)..**.** ^The
319b0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
319c0 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 is the value to
319d0 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 bind to the para
319e0 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 meter..** ^If th
319f0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
31a00 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e r to sqlite3_bin
31a10 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 d_text() or sqli
31a20 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
31a30 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
31a40 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 bind_blob() is a
31a50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
31a60 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 en the fourth pa
31a70 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 rameter.** is ig
31a80 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e nored and the en
31a90 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 d result is the
31aa0 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f same as sqlite3_
31ab0 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a bind_null()..**.
31ac0 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f ** ^(In those ro
31ad0 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 utines that have
31ae0 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 a fourth argume
31af0 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 nt, its value is
31b00 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
31b10 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 f bytes in the p
31b20 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 arameter. To be
31b30 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 clear: the valu
31b40 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 e is the.** numb
31b50 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f er of <u>bytes</
31b60 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c u> in the value,
31b70 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 not the number
31b80 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e of characters.)^
31b90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 .** ^If the four
31ba0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
31bb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
31bc0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 t() or sqlite3_b
31bd0 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 ind_text16().**
31be0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
31bf0 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 n the length of
31c00 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a the string is.**
31c10 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
31c20 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 ytes up to the f
31c30 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e irst zero termin
31c40 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 ator..** If the
31c50 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
31c60 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
31c70 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 _blob() is negat
31c80 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 ive, then.** the
31c90 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
31ca0 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 efined..** If a
31cb0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 non-negative fou
31cc0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
31cd0 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c provided to sql
31ce0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 ite3_bind_text()
31cf0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 .** or sqlite3_b
31d00 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 ind_text16() or
31d10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
31d20 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 t64() then.** th
31d30 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 at parameter mus
31d40 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 t be the byte of
31d50 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 fset.** where th
31d60 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 e NUL terminator
31d70 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 would occur ass
31d80 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 uming the string
31d90 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 were NUL.** ter
31da0 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 minated. If any
31db0 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 NUL characters
31dc0 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 occur at byte of
31dd0 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 fsets less than
31de0 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 .** the value of
31df0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
31e00 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 meter then the r
31e10 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 esulting string
31e20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f value will.** co
31e30 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e ntain embedded N
31e40 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 ULs. The result
31e50 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 of expressions
31e60 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 involving string
31e70 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 s.** with embedd
31e80 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 ed NULs is undef
31e90 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ined..**.** ^The
31ea0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 fifth argument
31eb0 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 to the BLOB and
31ec0 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 string binding i
31ed0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 nterfaces.** is
31ee0 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 a destructor use
31ef0 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 d to dispose of
31f00 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 the BLOB or.** s
31f10 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 tring after SQLi
31f20 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 te has finished
31f30 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 with it. ^The d
31f40 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c estructor is cal
31f50 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 led.** to dispos
31f60 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 e of the BLOB or
31f70 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 string even if
31f80 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 the call to the
31f90 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2c 0a bind API fails,.
31fa0 2a 2a 20 65 78 63 65 70 74 20 74 68 65 20 64 65 ** except the de
31fb0 73 74 72 75 63 74 6f 72 20 69 73 20 6e 6f 74 20 structor is not
31fc0 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 74 68 called if the th
31fd0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ird parameter is
31fe0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 a NULL.** point
31ff0 65 72 20 6f 72 20 74 68 65 20 66 6f 75 72 74 68 er or the fourth
32000 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 parameter is ne
32010 67 61 74 69 76 65 2e 0a 2a 2a 20 5e 49 66 20 74 gative..** ^If t
32020 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
32030 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 t is.** the spec
32040 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 ial value [SQLIT
32050 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 E_STATIC], then
32060 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 SQLite assumes t
32070 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 hat the.** infor
32080 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 mation is in sta
32090 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 tic, unmanaged s
320a0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f pace and does no
320b0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 t need to be fre
320c0 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 ed..** ^If the f
320d0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 ifth argument ha
320e0 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c s the value [SQL
320f0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 ITE_TRANSIENT],
32100 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d then.** SQLite m
32110 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 akes its own pri
32120 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 vate copy of the
32130 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c data immediatel
32140 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 y, before.** the
32150 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
32160 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
32170 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 s..**.** ^The si
32180 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 xth argument to
32190 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
321a0 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e t64() must be on
321b0 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f e of.** [SQLITE_
321c0 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 UTF8], [SQLITE_U
321d0 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 TF16], [SQLITE_U
321e0 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c TF16BE], or [SQL
321f0 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 ITE_UTF16LE].**
32200 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65 to specify the e
32210 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 ncoding of the t
32220 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 ext in the third
32230 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a parameter. If.
32240 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67 ** the sixth arg
32250 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
32260 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 _bind_text64() i
32270 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 s not one of the
32280 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 .** allowed valu
32290 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 es shown above,
322a0 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65 or if the text e
322b0 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 ncoding is diffe
322c0 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 rent.** from the
322d0 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 encoding specif
322e0 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68 ied by the sixth
322f0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e parameter, then
32300 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a the behavior.**
32310 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
32320 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
32330 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 3_bind_zeroblob(
32340 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 ) routine binds
32350 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 a BLOB of length
32360 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 N that.** is fi
32370 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 lled with zeroes
32380 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 . ^A zeroblob u
32390 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 ses a fixed amou
323a0 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 nt of memory.**
323b0 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 (just an integer
323c0 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a to hold its siz
323d0 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 e) while it is b
323e0 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a eing processed..
323f0 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 ** Zeroblobs are
32400 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 intended to ser
32410 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 ve as placeholde
32420 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f rs for BLOBs who
32430 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 se.** content is
32440 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 later written u
32450 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
32460 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 _blob_open | inc
32470 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f remental BLOB I/
32480 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 O] routines..**
32490 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 ^A negative valu
324a0 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c e for the zerobl
324b0 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 ob results in a
324c0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 zero-length BLOB
324d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
324e0 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 ite3_bind_pointe
324f0 72 28 53 2c 49 2c 50 2c 54 2c 44 29 20 72 6f 75 r(S,I,P,T,D) rou
32500 74 69 6e 65 20 63 61 75 73 65 73 20 74 68 65 20 tine causes the
32510 49 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 I-th parameter i
32520 6e 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 n.** [prepared s
32530 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20 68 tatement] S to h
32540 61 76 65 20 61 6e 20 53 51 4c 20 76 61 6c 75 65 ave an SQL value
32550 20 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20 74 6f of NULL, but to
32560 20 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73 73 6f also be.** asso
32570 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
32580 70 6f 69 6e 74 65 72 20 50 20 6f 66 20 74 79 70 pointer P of typ
32590 65 20 54 2e 20 20 5e 44 20 69 73 20 65 69 74 68 e T. ^D is eith
325a0 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 er a NULL pointe
325b0 72 20 6f 72 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 r or.** a pointe
325c0 72 20 74 6f 20 61 20 64 65 73 74 72 75 63 74 6f r to a destructo
325d0 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 50 r function for P
325e0 2e 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 . ^SQLite will i
325f0 6e 76 6f 6b 65 20 74 68 65 0a 2a 2a 20 64 65 73 nvoke the.** des
32600 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 tructor D with a
32610 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
32620 20 6f 66 20 50 20 77 68 65 6e 20 69 74 20 69 73 of P when it is
32630 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a finished using.
32640 2a 2a 20 50 2e 20 20 54 68 65 20 54 20 70 61 72 ** P. The T par
32650 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 ameter should be
32660 20 61 20 73 74 61 74 69 63 20 73 74 72 69 6e 67 a static string
32670 2c 20 70 72 65 66 65 72 61 62 6c 79 20 61 20 73 , preferably a s
32680 74 72 69 6e 67 0a 2a 2a 20 6c 69 74 65 72 61 6c tring.** literal
32690 2e 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 . The sqlite3_bi
326a0 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20 72 6f 75 nd_pointer() rou
326b0 74 69 6e 65 20 69 73 20 70 61 72 74 20 6f 66 20 tine is part of
326c0 74 68 65 0a 2a 2a 20 5b 70 6f 69 6e 74 65 72 20 the.** [pointer
326d0 70 61 73 73 69 6e 67 20 69 6e 74 65 72 66 61 63 passing interfac
326e0 65 5d 20 61 64 64 65 64 20 66 6f 72 20 53 51 4c e] added for SQL
326f0 69 74 65 20 33 2e 32 30 2e 30 2e 0a 2a 2a 0a 2a ite 3.20.0..**.*
32700 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 * ^If any of the
32710 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
32720 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 ) routines are c
32730 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c alled with a NUL
32740 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 L pointer.** for
32750 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
32760 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 tatement] or wit
32770 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 h a prepared sta
32780 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 tement for which
32790 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
327a0 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 p()] has been ca
327b0 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 lled more recent
327c0 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 ly than [sqlite3
327d0 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 _reset()],.** th
327e0 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c en the call will
327f0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
32800 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 MISUSE]. If any
32810 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 sqlite3_bind_()
32820 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 .** routine is p
32830 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 assed a [prepare
32840 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
32850 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c t has been final
32860 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 ized, the.** res
32870 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ult is undefined
32880 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 and probably ha
32890 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 rmful..**.** ^Bi
328a0 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 ndings are not c
328b0 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 leared by the [s
328c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
328d0 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 routine..** ^Unb
328e0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 ound parameters
328f0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 are interpreted
32900 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e as NULL..**.** ^
32910 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 The sqlite3_bind
32920 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 _* routines retu
32930 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f rn [SQLITE_OK] o
32940 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a n success or an.
32950 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ** [error code]
32960 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 if anything goes
32970 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c wrong..** ^[SQL
32980 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 ITE_TOOBIG] migh
32990 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 t be returned if
329a0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 the size of a s
329b0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a tring or BLOB.**
329c0 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 exceeds limits
329d0 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 imposed by [sqli
329e0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 te3_limit]([SQLI
329f0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d TE_LIMIT_LENGTH]
32a00 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ) or.** [SQLITE_
32a10 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 MAX_LENGTH]..**
32a20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 ^[SQLITE_RANGE]
32a30 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 is returned if t
32a40 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
32a50 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
32a60 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 range. ^[SQLITE
32a70 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 _NOMEM] is retur
32a80 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 ned if malloc()
32a90 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 fails..**.** See
32aa0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
32ab0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
32ac0 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c ount()],.** [sql
32ad0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
32ae0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 ter_name()], and
32af0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
32b00 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
32b10 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
32b20 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 3_bind_blob(sqli
32b30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
32b40 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
32b50 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 n, void(*)(void
32b60 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 *));.int sqlite3
32b70 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c _bind_blob64(sql
32b80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
32b90 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 const void*, sq
32ba0 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 lite3_uint64,.
32bb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
32bc0 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f void(*)(vo
32bd0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 id*));.int sqlit
32be0 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 e3_bind_double(s
32bf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
32c00 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 t, double);.int
32c10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 sqlite3_bind_int
32c20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
32c30 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 int, int);.int s
32c40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 qlite3_bind_int6
32c50 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
32c60 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e int, sqlite3_in
32c70 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 t64);.int sqlite
32c80 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 3_bind_null(sqli
32c90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b te3_stmt*, int);
32ca0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
32cb0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 d_text(sqlite3_s
32cc0 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 tmt*,int,const c
32cd0 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 har*,int,void(*)
32ce0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 (void*));.int sq
32cf0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
32d00 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
32d10 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 int, const void
32d20 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 *, int, void(*)(
32d30 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c void*));.int sql
32d40 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 ite3_bind_text64
32d50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
32d60 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a int, const char*
32d70 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 , sqlite3_uint64
32d80 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
32d90 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 void(
32da0 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 *)(void*), unsig
32db0 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e ned char encodin
32dc0 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f g);.int sqlite3_
32dd0 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 bind_value(sqlit
32de0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
32df0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c onst sqlite3_val
32e00 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ue*);.int sqlite
32e10 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 73 3_bind_pointer(s
32e20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
32e30 74 2c 20 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 t, void*, const
32e40 63 68 61 72 2a 2c 76 6f 69 64 28 2a 29 28 76 6f char*,void(*)(vo
32e50 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 id*));.int sqlit
32e60 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 e3_bind_zeroblob
32e70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
32e80 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 int, int n);.int
32e90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 sqlite3_bind_ze
32ea0 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 roblob64(sqlite3
32eb0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c _stmt*, int, sql
32ec0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f ite3_uint64);../
32ed0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
32ee0 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 umber Of SQL Par
32ef0 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f ameters.** METHO
32f00 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
32f10 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
32f20 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ine can be used
32f30 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 to find the numb
32f40 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d er of [SQL param
32f50 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b eters].** in a [
32f60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
32f70 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 nt]. SQL parame
32f80 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 ters are tokens
32f90 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 of the.** form "
32fa0 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 ?", "?NNN", ":AA
32fb0 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 A", "$AAA", or "
32fc0 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 @AAA" that serve
32fd0 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 as.** placehold
32fe0 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 ers for values t
32ff0 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 hat are [sqlite3
33000 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 _bind_blob | bou
33010 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 nd].** to the pa
33020 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 rameters at a la
33030 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 ter time..**.**
33040 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 ^(This routine a
33050 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 ctually returns
33060 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 the index of the
33070 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d largest (rightm
33080 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 ost).** paramete
33090 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 r. For all forms
330a0 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 except ?NNN, th
330b0 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f is will correspo
330c0 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d nd to the.** num
330d0 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 ber of unique pa
330e0 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 rameters. If pa
330f0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 rameters of the
33100 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 ?NNN form are us
33110 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 ed,.** there may
33120 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 be gaps in the
33130 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 list.)^.**.** Se
33140 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
33150 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
33160 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
33170 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
33180 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 ameter_name()],
33190 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
331a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
331b0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 ndex()]..*/.int
331c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
331d0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c ameter_count(sql
331e0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
331f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 .** CAPI3REF: Na
33200 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 me Of A Host Par
33210 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 ameter.** METHOD
33220 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
33230 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
33240 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
33250 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 _name(P,N) inter
33260 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 face returns.**
33270 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
33280 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 N-th [SQL parame
33290 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 ter] in the [pre
332a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
332b0 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 P..** ^(SQL par
332c0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 ameters of the f
332d0 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a orm "?NNN" or ":
332e0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f AAA" or "@AAA" o
332f0 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 r "$AAA".** have
33300 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 a name which is
33310 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e the string "?NN
33320 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 N" or ":AAA" or
33330 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 "@AAA" or "$AAA"
33340 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 .** respectively
33350 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f ..** In other wo
33360 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c rds, the initial
33370 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 ":" or "$" or "
33380 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 @" or "?".** is
33390 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 included as part
333a0 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a of the name.)^.
333b0 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f ** ^Parameters o
333c0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 f the form "?" w
333d0 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 ithout a followi
333e0 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 ng integer have
333f0 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 no name.** and a
33400 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 re referred to a
33410 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 s "nameless" or
33420 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d "anonymous param
33430 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 eters"..**.** ^T
33440 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 he first host pa
33450 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 rameter has an i
33460 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 ndex of 1, not 0
33470 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
33480 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f value N is out o
33490 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 f range or if th
334a0 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 e N-th parameter
334b0 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c is.** nameless,
334c0 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 then NULL is re
334d0 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 turned. ^The re
334e0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 turned string is
334f0 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 .** always in UT
33500 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 F-8 encoding eve
33510 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 n if the named p
33520 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 arameter was.**
33530 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 originally speci
33540 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 fied as UTF-16 i
33550 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 n [sqlite3_prepa
33560 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c re16()],.** [sql
33570 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
33580 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 2()], or [sqlite
33590 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 3_prepare16_v3()
335a0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 ]..**.** See als
335b0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
335c0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
335d0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nd()],.** [sqlit
335e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
335f0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a r_count()], and.
33600 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
33610 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
33620 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ()]..*/.const ch
33630 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 ar *sqlite3_bind
33640 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
33650 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
33660 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
33670 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 3REF: Index Of A
33680 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 Parameter With
33690 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 A Given Name.**
336a0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
336b0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 stmt.**.** ^Retu
336c0 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 rn the index of
336d0 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 an SQL parameter
336e0 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e given its name.
336f0 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 ^The.** index
33700 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 value returned i
33710 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 s suitable for u
33720 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 se as the second
33730 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f .** parameter to
33740 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
33750 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 lob|sqlite3_bind
33760 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a ()]. ^A zero.**
33770 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 is returned if
33780 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 no matching para
33790 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 meter is found.
337a0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a ^The parameter.
337b0 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 ** name must be
337c0 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 given in UTF-8 e
337d0 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 ven if the origi
337e0 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a nal statement.**
337f0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 was prepared fr
33800 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 om UTF-16 text u
33810 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 sing [sqlite3_pr
33820 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 epare16_v2()] or
33830 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
33840 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a pare16_v3()]..**
33850 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
33860 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
33870 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
33880 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
33890 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
338a0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 nt()], and.** [s
338b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
338c0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a meter_name()]..*
338d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 /.int sqlite3_bi
338e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
338f0 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ex(sqlite3_stmt*
33900 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
33910 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ame);../*.** CAP
33920 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c I3REF: Reset All
33930 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 Bindings On A P
33940 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
33950 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
33960 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
33970 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 ^Contrary to the
33980 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 intuition of ma
33990 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ny, [sqlite3_res
339a0 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 et()] does not r
339b0 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c eset.** the [sql
339c0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c ite3_bind_blob |
339d0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 bindings] on a
339e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
339f0 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 ent]..** ^Use th
33a00 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 is routine to re
33a10 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 set all host par
33a20 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e ameters to NULL.
33a30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
33a40 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 clear_bindings(s
33a50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
33a60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
33a70 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e Number Of Column
33a80 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 s In A Result Se
33a90 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
33aa0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
33ab0 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 ^Return the numb
33ac0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
33ad0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
33ae0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a returned by the.
33af0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
33b00 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69 tement]. ^If thi
33b10 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
33b20 73 20 30 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 s 0, that means
33b30 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the .** [prepare
33b40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 72 65 74 d statement] ret
33b50 75 72 6e 73 20 6e 6f 20 64 61 74 61 20 28 66 6f urns no data (fo
33b60 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 r example an [UP
33b70 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65 DATE])..** ^Howe
33b80 76 65 72 2c 20 6a 75 73 74 20 62 65 63 61 75 73 ver, just becaus
33b90 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 e this routine r
33ba0 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76 eturns a positiv
33bb0 65 20 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f e number does no
33bc0 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f t.** mean that o
33bd0 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 ne or more rows
33be0 6f 66 20 64 61 74 61 20 77 69 6c 6c 20 62 65 20 of data will be
33bf0 72 65 74 75 72 6e 65 64 2e 20 20 5e 41 20 53 45 returned. ^A SE
33c00 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a LECT statement.*
33c10 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 68 61 * will always ha
33c20 76 65 20 61 20 70 6f 73 69 74 69 76 65 20 73 71 ve a positive sq
33c30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 lite3_column_cou
33c40 6e 74 28 29 20 62 75 74 20 64 65 70 65 6e 64 69 nt() but dependi
33c50 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45 ng on the.** WHE
33c60 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 RE clause constr
33c70 61 69 6e 74 73 20 61 6e 64 20 74 68 65 20 74 61 aints and the ta
33c80 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20 ble content, it
33c90 6d 69 67 68 74 20 72 65 74 75 72 6e 20 6e 6f 20 might return no
33ca0 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 rows..**.** See
33cb0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 also: [sqlite3_d
33cc0 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a ata_count()].*/.
33cd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
33ce0 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 mn_count(sqlite3
33cf0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
33d00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
33d10 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 Column Names In
33d20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 A Result Set.**
33d30 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
33d40 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 stmt.**.** ^Thes
33d50 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
33d60 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 n the name assig
33d70 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 ned to a particu
33d80 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e lar column.** in
33d90 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
33da0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 of a [SELECT] st
33db0 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 atement. ^The s
33dc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
33dd0 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 me().** interfac
33de0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
33df0 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 ter to a zero-te
33e00 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
33e10 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c tring.** and sql
33e20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
33e30 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 16() returns a p
33e40 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f ointer to a zero
33e50 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 -terminated.** U
33e60 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e TF-16 string. ^
33e70 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
33e80 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 ter is the [prep
33e90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
33ea0 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e ** that implemen
33eb0 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 ts the [SELECT]
33ec0 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 statement. ^The
33ed0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
33ee0 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d is the.** colum
33ef0 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 n number. ^The
33f00 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 leftmost column
33f10 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a is number 0..**.
33f20 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 ** ^The returned
33f30 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 string pointer
33f40 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 is valid until e
33f50 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 ither the [prepa
33f60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a red statement].*
33f70 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 * is destroyed b
33f80 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c y [sqlite3_final
33f90 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 ize()] or until
33fa0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
33fb0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a automatically.*
33fc0 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 * reprepared by
33fd0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 the first call t
33fe0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
33ff0 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 )] for a particu
34000 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e lar run.** or un
34010 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c til the next cal
34020 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f l to.** sqlite3_
34030 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 column_name() or
34040 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
34050 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 name16() on the
34060 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a same column..**.
34070 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d ** ^If sqlite3_m
34080 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 alloc() fails du
34090 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 ring the process
340a0 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f ing of either ro
340b0 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 utine.** (for ex
340c0 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 ample during a c
340d0 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 onversion from U
340e0 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 TF-8 to UTF-16)
340f0 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 then a.** NULL p
34100 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e ointer is return
34110 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e ed..**.** ^The n
34120 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 ame of a result
34130 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 column is the va
34140 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 lue of the "AS"
34150 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 clause for.** th
34160 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 at column, if th
34170 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 ere is an AS cla
34180 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 use. If there i
34190 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a s no AS clause.*
341a0 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 * then the name
341b0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 of the column is
341c0 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 unspecified and
341d0 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d may change from
341e0 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 .** one release
341f0 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 of SQLite to the
34200 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 next..*/.const
34210 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
34220 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 lumn_name(sqlite
34230 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 3_stmt*, int N);
34240 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
34250 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
34260 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
34270 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a , int N);../*.**
34280 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 CAPI3REF: Sourc
34290 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 e Of Data In A Q
342a0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d uery Result.** M
342b0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
342c0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 tmt.**.** ^These
342d0 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 routines provid
342e0 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 e a means to det
342f0 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 ermine the datab
34300 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a ase, table, and.
34310 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 ** table column
34320 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 that is the orig
34330 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c in of a particul
34340 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e ar result column
34350 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 in.** [SELECT]
34360 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 statement..** ^T
34370 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
34380 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 atabase or table
34390 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 or column can b
343a0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a e returned as.**
343b0 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 either a UTF-8
343c0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 or UTF-16 string
343d0 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 . ^The _databas
343e0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 e_ routines retu
343f0 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 rn.** the databa
34400 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 se name, the _ta
34410 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 ble_ routines re
34420 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e turn the table n
34430 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 ame, and.** the
34440 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 origin_ routines
34450 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 return the colu
34460 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 mn name..** ^The
34470 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
34480 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 is valid until
34490 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
344a0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 atement] is dest
344b0 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b royed.** using [
344c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
344d0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 ()] or until the
344e0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 statement is au
344f0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 tomatically.** r
34500 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 eprepared by the
34510 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b first call to [
34520 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
34530 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 for a particular
34540 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c run.** or until
34550 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d the same inform
34560 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 ation is request
34570 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 ed.** again in a
34580 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 different encod
34590 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ing..**.** ^The
345a0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 names returned a
345b0 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 re the original
345c0 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 un-aliased names
345d0 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 of the.** datab
345e0 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 ase, table, and
345f0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 column..**.** ^T
34600 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
34610 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 t to these inter
34620 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 faces is a [prep
34630 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
34640 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 .** ^These funct
34650 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f ions return info
34660 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 rmation about th
34670 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c e Nth result col
34680 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a umn returned by.
34690 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 ** the statement
346a0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
346b0 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e second function
346c0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 argument..** ^T
346d0 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c he left-most col
346e0 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 umn is column 0
346f0 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e for these routin
34700 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 es..**.** ^If th
34710 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 e Nth column ret
34720 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 urned by the sta
34730 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 tement is an exp
34740 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 ression or.** su
34750 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f bquery and is no
34760 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 t a column value
34770 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 , then all of th
34780 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 ese functions re
34790 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e turn.** NULL. ^
347a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 These routine mi
347b0 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 ght also return
347c0 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 NULL if a memory
347d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f allocation erro
347e0 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f r.** occurs. ^O
347f0 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 therwise, they r
34800 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f eturn the name o
34810 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 f the attached d
34820 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a atabase, table,.
34830 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 ** or column tha
34840 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 t query result c
34850 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 olumn was extrac
34860 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 ted from..**.**
34870 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 ^As with all oth
34880 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 er SQLite APIs,
34890 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 those whose name
348a0 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 s end with "16"
348b0 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 return.** UTF-16
348c0 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 encoded strings
348d0 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 and the other f
348e0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 unctions return
348f0 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 UTF-8..**.** ^Th
34900 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c ese APIs are onl
34910 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 y available if t
34920 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 he library was c
34930 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
34940 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 .** [SQLITE_ENAB
34950 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 LE_COLUMN_METADA
34960 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 TA] C-preprocess
34970 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a or symbol..**.**
34980 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 If two or more
34990 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 threads call one
349a0 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 or more of thes
349b0 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e e routines again
349c0 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 st the same.** p
349d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
349e0 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 t and column at
349f0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 the same time th
34a00 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 en the results a
34a10 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e re.** undefined.
34a20 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 .**.** If two or
34a30 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 more threads ca
34a40 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a ll one or more.*
34a50 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
34a60 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 n_database_name
34a70 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 | column metadat
34a80 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a a interfaces].**
34a90 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 for the same [p
34aa0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
34ab0 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f t] and result co
34ac0 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 lumn.** at the s
34ad0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 ame time then th
34ae0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
34af0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 defined..*/.cons
34b00 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
34b10 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
34b20 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
34b30 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 t*,int);.const v
34b40 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
34b50 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d umn_database_nam
34b60 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
34b70 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 *,int);.const ch
34b80 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
34b90 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 mn_table_name(sq
34ba0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
34bb0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
34bc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 lite3_column_tab
34bd0 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 le_name16(sqlite
34be0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
34bf0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
34c00 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 3_column_origin_
34c10 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
34c20 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 t*,int);.const v
34c30 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
34c40 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 umn_origin_name1
34c50 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
34c60 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
34c70 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 I3REF: Declared
34c80 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 Datatype Of A Qu
34c90 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 ery Result.** ME
34ca0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
34cb0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 mt.**.** ^(The f
34cc0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
34cd0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 s a [prepared st
34ce0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 atement]..** If
34cf0 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 this statement i
34d00 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 s a [SELECT] sta
34d10 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e tement and the N
34d20 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 th column of the
34d30 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 .** returned res
34d40 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 ult set of that
34d50 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 [SELECT] is a ta
34d60 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 ble column (not
34d70 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e an.** expression
34d80 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 or subquery) th
34d90 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 en the declared
34da0 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c type of the tabl
34db0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 e.** column is r
34dc0 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 eturned.)^ ^If
34dd0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f the Nth column o
34de0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
34df0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 is an.** expres
34e00 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 sion or subquery
34e10 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f , then a NULL po
34e20 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 inter is returne
34e30 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 d..** ^The retur
34e40 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c ned string is al
34e50 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 ways UTF-8 encod
34e60 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 ed..**.** ^(For
34e70 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 example, given t
34e80 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 he database sche
34e90 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 ma:.**.** CREATE
34ea0 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 TABLE t1(c1 VAR
34eb0 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 IANT);.**.** and
34ec0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 the following s
34ed0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 tatement to be c
34ee0 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 ompiled:.**.** S
34ef0 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 ELECT c1 + 1, c1
34f00 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 FROM t1;.**.**
34f10 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 this routine wou
34f20 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 ld return the st
34f30 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 ring "VARIANT" f
34f40 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 or the second re
34f50 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 sult.** column (
34f60 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c i==1), and a NUL
34f70 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 L pointer for th
34f80 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 e first result c
34f90 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a olumn (i==0).)^.
34fa0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 **.** ^SQLite us
34fb0 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 es dynamic run-t
34fc0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f ime typing. ^So
34fd0 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 just because a
34fe0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 column.** is dec
34ff0 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e lared to contain
35000 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 a particular ty
35010 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e pe does not mean
35020 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 that the.** dat
35030 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 a stored in that
35040 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 column is of th
35050 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e e declared type.
35060 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 SQLite is.** s
35070 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 trongly typed, b
35080 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 ut the typing is
35090 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 dynamic not sta
350a0 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 tic. ^Type.** i
350b0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 s associated wit
350c0 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c h individual val
350d0 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 ues, not with th
350e0 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 e containers.**
350f0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f used to hold tho
35100 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f se values..*/.co
35110 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
35120 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 3_column_decltyp
35130 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
35140 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 int);.const void
35150 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
35160 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 _decltype16(sqli
35170 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
35180 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
35190 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c Evaluate An SQL
351a0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 Statement.** ME
351b0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
351c0 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 mt.**.** After a
351d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
351e0 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 ment] has been p
351f0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 61 6e repared using an
35200 79 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 y of.** [sqlite3
35210 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 _prepare_v2()],
35220 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
35230 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v3()], [sqlite3
35240 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
35250 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ,.** or [sqlite3
35260 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d _prepare16_v3()]
35270 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c or one of the l
35280 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 egacy.** interfa
35290 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ces [sqlite3_pre
352a0 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 pare()] or [sqli
352b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
352c0 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a , this function.
352d0 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 ** must be calle
352e0 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 d one or more ti
352f0 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 mes to evaluate
35300 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a the statement..*
35310 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 *.** The details
35320 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 of the behavior
35330 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
35340 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 step() interface
35350 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 depend.** on wh
35360 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d ether the statem
35370 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 ent was prepared
35380 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 using the newer
35390 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 "vX" interfaces
353a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
353b0 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c pare_v3()], [sql
353c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
353d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 )], [sqlite3_pre
353e0 70 61 72 65 31 36 5f 76 33 28 29 5d 2c 0a 2a 2a pare16_v3()],.**
353f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
35400 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 e16_v2()] or the
35410 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a older legacy.**
35420 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c interfaces [sql
35430 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
35440 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
35450 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 pare16()]. The
35460 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 use of the.** ne
35470 77 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 w "vX" interface
35480 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
35490 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 for new applicat
354a0 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 ions but the leg
354b0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 acy.** interface
354c0 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 will continue t
354d0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a o be supported..
354e0 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 **.** ^In the le
354f0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 gacy interface,
35500 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
35510 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 will be either
35520 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a [SQLITE_BUSY],.*
35530 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c * [SQLITE_DONE],
35540 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b [SQLITE_ROW], [
35550 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f SQLITE_ERROR], o
35560 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 r [SQLITE_MISUSE
35570 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 ]..** ^With the
35580 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 "v2" interface,
35590 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 any of the other
355a0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 [result codes]
355b0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 or.** [extended
355c0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 result codes] mi
355d0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 ght be returned
355e0 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e as well..**.** ^
355f0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 [SQLITE_BUSY] me
35600 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 ans that the dat
35610 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 abase engine was
35620 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 unable to acqui
35630 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 re the.** databa
35640 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 se locks it need
35650 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e s to do its job.
35660 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d ^If the statem
35670 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 ent is a [COMMIT
35680 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f ].** or occurs o
35690 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 utside of an exp
356a0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f licit transactio
356b0 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 n, then you can
356c0 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 retry the.** sta
356d0 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 tement. If the
356e0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 statement is not
356f0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 a [COMMIT] and
35700 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e occurs within an
35710 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 .** explicit tra
35720 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f nsaction then yo
35730 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 u should rollbac
35740 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f k the transactio
35750 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 n before.** cont
35760 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b inuing..**.** ^[
35770 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 SQLITE_DONE] mea
35780 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 ns that the stat
35790 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 ement has finish
357a0 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 ed executing.**
357b0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 successfully. s
357c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 qlite3_step() sh
357d0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c ould not be call
357e0 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 ed again on this
357f0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 virtual.** mach
35800 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 ine without firs
35810 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 t calling [sqlit
35820 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 e3_reset()] to r
35830 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c eset the virtual
35840 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b .** machine back
35850 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 to its initial
35860 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 state..**.** ^If
35870 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
35880 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 nt being execute
35890 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 d returns any da
358a0 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 ta, then [SQLITE
358b0 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 _ROW].** is retu
358c0 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 rned each time a
358d0 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 new row of data
358e0 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 is ready for pr
358f0 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a ocessing by the.
35900 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 ** caller. The v
35910 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 alues may be acc
35920 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 essed using the
35930 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 [column access f
35940 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 unctions]..** sq
35950 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 lite3_step() is
35960 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 called again to
35970 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 retrieve the nex
35980 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a t row of data..*
35990 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 *.** ^[SQLITE_ER
359a0 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 ROR] means that
359b0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 a run-time error
359c0 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 (such as a cons
359d0 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 traint.** violat
359e0 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 ion) has occurre
359f0 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 d. sqlite3_step
35a00 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 () should not be
35a10 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e called again on
35a20 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 .** the VM. More
35a30 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 information may
35a40 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c be found by cal
35a50 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 ling [sqlite3_er
35a60 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 rmsg()]..** ^Wit
35a70 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 h the legacy int
35a80 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 erface, a more s
35a90 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f pecific error co
35aa0 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c de (for example,
35ab0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 .** [SQLITE_INTE
35ac0 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f RRUPT], [SQLITE_
35ad0 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 SCHEMA], [SQLITE
35ae0 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 _CORRUPT], and s
35af0 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 o forth).** can
35b00 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 be obtained by c
35b10 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
35b20 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a reset()] on the.
35b30 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
35b40 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 tement]. ^In th
35b50 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
35b60 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 ,.** the more sp
35b70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 ecific error cod
35b80 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 e is returned di
35b90 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 rectly by sqlite
35ba0 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 3_step()..**.**
35bb0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
35bc0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 means that the t
35bd0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 his routine was
35be0 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 called inappropr
35bf0 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 iately..** Perha
35c00 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 ps it was called
35c10 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 on a [prepared
35c20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
35c30 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 has.** already b
35c40 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e een [sqlite3_fin
35c50 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 alize | finalize
35c60 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 d] or on one tha
35c70 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 t had.** previou
35c80 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 sly returned [SQ
35c90 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b LITE_ERROR] or [
35ca0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f SQLITE_DONE]. O
35cb0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 r it could.** be
35cc0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 the case that t
35cd0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
35ce0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 connection is b
35cf0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f eing used by two
35d00 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 or.** more thre
35d10 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 ads at the same
35d20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a moment in time..
35d30 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 **.** For all ve
35d40 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
35d50 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 up to and inclu
35d60 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 ding 3.6.23.1, a
35d70 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
35d80 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 ite3_reset()] wa
35d90 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 s required after
35da0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
35db0 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e returned anythin
35dc0 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 g.** other than
35dd0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 [SQLITE_ROW] bef
35de0 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 ore any subseque
35df0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 nt invocation of
35e00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 .** sqlite3_step
35e10 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 (). Failure to
35e20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 reset the prepar
35e30 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 ed statement usi
35e40 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ng .** [sqlite3_
35e50 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 reset()] would r
35e60 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c esult in an [SQL
35e70 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 ITE_MISUSE] retu
35e80 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 rn from.** sqlit
35e90 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 e3_step(). But
35ea0 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e 20 33 after [version 3
35eb0 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f .6.23.1] ([dateo
35ec0 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 f:3.6.23.1],.**
35ed0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 sqlite3_step() b
35ee0 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 egan.** calling
35ef0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
35f00 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 ] automatically
35f10 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 in this circumst
35f20 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 ance rather.** t
35f30 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 han returning [S
35f40 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
35f50 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 This is not cons
35f60 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 idered a compati
35f70 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 bility.** break
35f80 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c because any appl
35f90 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 ication that eve
35fa0 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 r receives an SQ
35fb0 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f LITE_MISUSE erro
35fc0 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 r.** is broken b
35fd0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 y definition. T
35fe0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f he [SQLITE_OMIT_
35ff0 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 AUTORESET] compi
36000 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a le-time option.*
36010 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f * can be used to
36020 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 restore the leg
36030 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a acy behavior..**
36040 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 .** <b>Goofy Int
36050 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 erface Alert:</b
36060 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 > In the legacy
36070 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 interface, the s
36080 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a qlite3_step().**
36090 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 API always retu
360a0 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 rns a generic er
360b0 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 ror code, [SQLIT
360c0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 E_ERROR], follow
360d0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 ing any.** error
360e0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
360f0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 ITE_BUSY] and [S
36100 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
36110 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a You must call.**
36120 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
36130 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
36140 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 inalize()] in or
36150 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 der to find one
36160 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 of the.** specif
36170 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ic [error codes]
36180 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 that better des
36190 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 cribes the error
361a0 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 ..** We admit th
361b0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f at this is a goo
361c0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 fy design. The
361d0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e problem has been
361e0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 fixed.** with t
361f0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
36200 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 e. If you prepa
36210 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 re all of your S
36220 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
36230 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
36240 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 6f 72 prepare_v3()] or
36250 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
36260 65 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 e_v2()].** or [s
36270 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
36280 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
36290 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 e3_prepare16_v3(
362a0 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 )] instead.** of
362b0 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c the legacy [sql
362c0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
362d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
362e0 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 pare16()] interf
362f0 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 aces,.** then th
36300 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 e more specific
36310 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 [error codes] ar
36320 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 e returned direc
36330 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 tly.** by sqlite
36340 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 3_step(). The u
36350 73 65 20 6f 66 20 74 68 65 20 22 76 58 22 20 69 se of the "vX" i
36360 6e 74 65 72 66 61 63 65 73 20 69 73 20 72 65 63 nterfaces is rec
36370 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 ommended..*/.int
36380 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 sqlite3_step(sq
36390 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
363a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
363b0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
363c0 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 in a result set
363d0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
363e0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
363f0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 The sqlite3_data
36400 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 _count(P) interf
36410 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
36420 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
36430 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 s in the.** curr
36440 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 ent row of the r
36450 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 esult set of [pr
36460 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
36470 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 ] P..** ^If prep
36480 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 ared statement P
36490 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 does not have r
364a0 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 esults ready to
364b0 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 return.** (via c
364c0 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c alls to the [sql
364d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 ite3_column_int
364e0 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e | sqlite3_column
364f0 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 _*()] of.** inte
36500 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c rfaces) then sql
36510 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
36520 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a P) returns 0..**
36530 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 ^The sqlite3_da
36540 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 ta_count(P) rout
36550 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 ine also returns
36560 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 0 if P is a NUL
36570 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 L pointer..** ^T
36580 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
36590 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 count(P) routine
365a0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 returns 0 if th
365b0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 e previous call
365c0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 to.** [sqlite3_s
365d0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 tep](P) returned
365e0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 [SQLITE_DONE].
365f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 ^The sqlite3_da
36600 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 ta_count(P).** w
36610 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a ill return non-z
36620 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 ero if previous
36630 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
36640 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e _step](P) return
36650 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f ed.** [SQLITE_RO
36660 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 W], except in th
36670 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 e case of the [P
36680 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 RAGMA incrementa
36690 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 l_vacuum].** whe
366a0 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 re it always ret
366b0 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 urns zero since
366c0 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 each step of tha
366d0 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 t multi-step.**
366e0 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 pragma returns 0
366f0 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 columns of data
36700 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
36710 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d : [sqlite3_colum
36720 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e n_count()].*/.in
36730 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 t sqlite3_data_c
36740 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
36750 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
36760 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 * CAPI3REF: Fund
36770 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 amental Datatype
36780 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 s.** KEYWORDS: S
36790 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a QLITE_TEXT.**.**
367a0 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 ^(Every value i
367b0 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 n SQLite has one
367c0 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 of five fundame
367d0 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a ntal datatypes:.
367e0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
367f0 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 i> 64-bit signed
36800 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e integer.** <li>
36810 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 64-bit IEEE flo
36820 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 ating point numb
36830 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e er.** <li> strin
36840 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a g.** <li> BLOB.*
36850 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c * <li> NULL.** <
36860 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 /ul>)^.**.** The
36870 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 se constants are
36880 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 codes for each
36890 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a of those types..
368a0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
368b0 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 the SQLITE_TEXT
368c0 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 constant was als
368d0 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 o used in SQLite
368e0 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f version 2.** fo
368f0 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 r a completely d
36900 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 ifferent meaning
36910 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 . Software that
36920 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 links against b
36930 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 oth.** SQLite ve
36940 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 rsion 2 and SQLi
36950 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f te version 3 sho
36960 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f uld use SQLITE3_
36970 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c TEXT, not.** SQL
36980 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 ITE_TEXT..*/.#de
36990 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
369a0 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 GER 1.#define S
369b0 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 QLITE_FLOAT 2
369c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
369d0 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 BLOB 4.#defi
369e0 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 ne SQLITE_NULL
369f0 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 5.#ifdef SQLI
36a00 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 TE_TEXT.# undef
36a10 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 SQLITE_TEXT.#els
36a20 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 e.# define SQLIT
36a30 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e E_TEXT 3.#en
36a40 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 dif.#define SQLI
36a50 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a TE3_TEXT 3..
36a60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
36a70 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 Result Values Fr
36a80 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 om A Query.** KE
36a90 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 YWORDS: {column
36aa0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 access functions
36ab0 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c }.** METHOD: sql
36ac0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
36ad0 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f 62 3e 0a <b>Summary:</b>.
36ae0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
36af0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 30 20 63 table border=0 c
36b00 65 6c 6c 70 61 64 64 69 6e 67 3d 30 20 63 65 6c ellpadding=0 cel
36b10 6c 73 70 61 63 69 6e 67 3d 30 3e 0a 2a 2a 20 3c lspacing=0>.** <
36b20 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 tr><td><b>sqlite
36b30 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f 62 3_column_blob</b
36b40 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 42 ><td>→<td>B
36b50 4c 4f 42 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 LOB result.** <t
36b60 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 r><td><b>sqlite3
36b70 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 3c 2f _column_double</
36b80 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e b><td>→<td>
36b90 52 45 41 4c 20 72 65 73 75 6c 74 0a 2a 2a 20 3c REAL result.** <
36ba0 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 tr><td><b>sqlite
36bb0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 3c 2f 62 3e 3_column_int</b>
36bc0 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 33 32 <td>→<td>32
36bd0 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73 -bit INTEGER res
36be0 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c ult.** <tr><td><
36bf0 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e b>sqlite3_column
36c00 5f 69 6e 74 36 34 3c 2f 62 3e 3c 74 64 3e 26 72 _int64</b><td>&r
36c10 61 72 72 3b 3c 74 64 3e 36 34 2d 62 69 74 20 49 arr;<td>64-bit I
36c20 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a NTEGER result.**
36c30 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 <tr><td><b>sqli
36c40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 3c te3_column_text<
36c50 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 /b><td>→<td
36c60 3e 55 54 46 2d 38 20 54 45 58 54 20 72 65 73 75 >UTF-8 TEXT resu
36c70 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 lt.** <tr><td><b
36c80 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
36c90 74 65 78 74 31 36 3c 2f 62 3e 3c 74 64 3e 26 72 text16</b><td>&r
36ca0 61 72 72 3b 3c 74 64 3e 55 54 46 2d 31 36 20 54 arr;<td>UTF-16 T
36cb0 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 EXT result.** <t
36cc0 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 r><td><b>sqlite3
36cd0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 3c 2f 62 _column_value</b
36ce0 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 54 ><td>→<td>T
36cf0 68 65 20 72 65 73 75 6c 74 20 61 73 20 61 6e 20 he result as an
36d00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
36d10 75 65 7c 75 6e 70 72 6f 74 65 63 74 65 64 20 73 ue|unprotected s
36d20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
36d30 6a 65 63 74 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 ject..** <tr><td
36d40 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 > <td> 
36d50 3b 3c 74 64 3e 26 6e 62 73 70 3b 0a 2a 2a 20 3c ;<td> .** <
36d60 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 tr><td><b>sqlite
36d70 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 3c 2f 3_column_bytes</
36d80 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e b><td>→<td>
36d90 53 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 0a 2a Size of a BLOB.*
36da0 2a 20 6f 72 20 61 20 55 54 46 2d 38 20 54 45 58 * or a UTF-8 TEX
36db0 54 20 72 65 73 75 6c 74 20 69 6e 20 62 79 74 65 T result in byte
36dc0 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e s.** <tr><td><b>
36dd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
36de0 79 74 65 73 31 36 26 6e 62 73 70 3b 26 6e 62 73 ytes16 &nbs
36df0 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74 64 3e 26 72 p;</b>.** <td>&r
36e00 61 72 72 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b arr;
36e10 3c 74 64 3e 53 69 7a 65 20 6f 66 20 55 54 46 2d <td>Size of UTF-
36e20 31 36 0a 2a 2a 20 54 45 58 54 20 69 6e 20 62 79 16.** TEXT in by
36e30 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c tes.** <tr><td><
36e40 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e b>sqlite3_column
36e50 5f 74 79 70 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 _type</b><td>&ra
36e60 72 72 3b 3c 74 64 3e 44 65 66 61 75 6c 74 0a 2a rr;<td>Default.*
36e70 2a 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 * datatype of th
36e80 65 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 2f 74 61 e result.** </ta
36e90 62 6c 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 ble></blockquote
36ea0 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 74 61 69 >.**.** <b>Detai
36eb0 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 ls:</b>.**.** ^T
36ec0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
36ed0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e turn information
36ee0 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 about a single
36ef0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 column of the cu
36f00 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 rrent.** result
36f10 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 row of a query.
36f20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 ^In every case
36f30 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
36f40 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a nt is a pointer.
36f50 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 ** to the [prepa
36f60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
36f70 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 hat is being eva
36f80 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c luated (the [sql
36f90 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 ite3_stmt*].** t
36fa0 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 hat was returned
36fb0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 from [sqlite3_p
36fc0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
36fd0 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 one of its varia
36fe0 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 nts).** and the
36ff0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
37000 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 is the index of
37010 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 the column for w
37020 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e hich information
37030 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 .** should be re
37040 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 turned. ^The lef
37050 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 tmost column of
37060 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 the result set h
37070 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a as the index 0..
37080 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f ** ^The number o
37090 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
370a0 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 result can be d
370b0 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a etermined using.
370c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
370d0 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a mn_count()]..**.
370e0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 ** If the SQL st
370f0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 atement does not
37100 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 currently point
37110 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c to a valid row,
37120 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f or if the.** co
37130 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 lumn index is ou
37140 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 t of range, the
37150 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 result is undefi
37160 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f ned..** These ro
37170 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 utines may only
37180 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 be called when t
37190 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 he most recent c
371a0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 all to.** [sqlit
371b0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 e3_step()] has r
371c0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
371d0 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 ROW] and neither
371e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
371f0 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 et()] nor [sqlit
37200 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 e3_finalize()] h
37210 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 ave been called
37220 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a subsequently..**
37230 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 If any of these
37240 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 routines are ca
37250 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 lled after [sqli
37260 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a te3_reset()] or.
37270 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ** [sqlite3_fina
37280 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 lize()] or after
37290 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
372a0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a ] has returned.*
372b0 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 * something othe
372c0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 r than [SQLITE_R
372d0 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 OW], the results
372e0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
372f0 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 ** If [sqlite3_s
37300 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 tep()] or [sqlit
37310 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b e3_reset()] or [
37320 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
37330 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 ()].** are calle
37340 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 d from a differe
37350 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 nt thread while
37360 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 any of these rou
37370 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e tines.** are pen
37380 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 ding, then the r
37390 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 esults are undef
373a0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ined..**.** The
373b0 66 69 72 73 74 20 73 69 78 20 69 6e 74 65 72 66 first six interf
373c0 61 63 65 73 20 28 5f 62 6c 6f 62 2c 20 5f 64 6f aces (_blob, _do
373d0 75 62 6c 65 2c 20 5f 69 6e 74 2c 20 5f 69 6e 74 uble, _int, _int
373e0 36 34 2c 20 5f 74 65 78 74 2c 20 61 6e 64 20 5f 64, _text, and _
373f0 74 65 78 74 31 36 29 0a 2a 2a 20 65 61 63 68 20 text16).** each
37400 72 65 74 75 72 6e 20 74 68 65 20 76 61 6c 75 65 return the value
37410 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c of a result col
37420 75 6d 6e 20 69 6e 20 61 20 73 70 65 63 69 66 69 umn in a specifi
37430 63 20 64 61 74 61 20 66 6f 72 6d 61 74 2e 20 20 c data format.
37440 49 66 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 If.** the result
37450 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f 74 20 69 column is not i
37460 6e 69 74 69 61 6c 6c 79 20 69 6e 20 74 68 65 20 nitially in the
37470 72 65 71 75 65 73 74 65 64 20 66 6f 72 6d 61 74 requested format
37480 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a (for example,.*
37490 2a 20 69 66 20 74 68 65 20 71 75 65 72 79 20 72 * if the query r
374a0 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 eturns an intege
374b0 72 20 62 75 74 20 74 68 65 20 73 71 6c 69 74 65 r but the sqlite
374c0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
374d0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 interface.** is
374e0 75 73 65 64 20 74 6f 20 65 78 74 72 61 63 74 20 used to extract
374f0 74 68 65 20 76 61 6c 75 65 29 20 74 68 65 6e 20 the value) then
37500 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70 an automatic typ
37510 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 e conversion is
37520 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a performed..**.**
37530 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f ^The sqlite3_co
37540 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 lumn_type() rout
37550 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a ine returns the.
37560 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 ** [SQLITE_INTEG
37570 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f ER | datatype co
37580 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 de] for the init
37590 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a ial data type.**
375a0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 of the result c
375b0 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 olumn. ^The ret
375c0 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f urned value is o
375d0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e ne of [SQLITE_IN
375e0 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 TEGER],.** [SQLI
375f0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 TE_FLOAT], [SQLI
37600 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 TE_TEXT], [SQLIT
37610 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c E_BLOB], or [SQL
37620 49 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54 68 ITE_NULL]..** Th
37630 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
37640 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e f sqlite3_column
37650 5f 74 79 70 65 28 29 20 63 61 6e 20 62 65 20 75 _type() can be u
37660 73 65 64 20 74 6f 20 64 65 63 69 64 65 20 77 68 sed to decide wh
37670 69 63 68 0a 2a 2a 20 6f 66 20 74 68 65 20 66 69 ich.** of the fi
37680 72 73 74 20 73 69 78 20 69 6e 74 65 72 66 61 63 rst six interfac
37690 65 20 73 68 6f 75 6c 64 20 62 65 20 75 73 65 64 e should be used
376a0 20 74 6f 20 65 78 74 72 61 63 74 20 74 68 65 20 to extract the
376b0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a column value..**
376c0 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 The value retur
376d0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
376e0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
376f0 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 only meaningful
37700 69 66 20 6e 6f 0a 2a 2a 20 61 75 74 6f 6d 61 74 if no.** automat
37710 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 ic type conversi
37720 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 ons have occurre
37730 64 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 20 d for the value
37740 69 6e 20 71 75 65 73 74 69 6f 6e 2e 20 20 0a 2a in question. .*
37750 2a 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 * After a type c
37760 6f 6e 76 65 72 73 69 6f 6e 2c 20 74 68 65 20 72 onversion, the r
37770 65 73 75 6c 74 20 6f 66 20 63 61 6c 6c 69 6e 67 esult of calling
37780 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
37790 74 79 70 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 type().** is und
377a0 65 66 69 6e 65 64 2c 20 74 68 6f 75 67 68 20 68 efined, though h
377b0 61 72 6d 6c 65 73 73 2e 20 20 46 75 74 75 72 65 armless. Future
377c0 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 .** versions of
377d0 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 SQLite may chang
377e0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f e the behavior o
377f0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e f sqlite3_column
37800 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f _type().** follo
37810 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 wing a type conv
37820 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 ersion..**.** If
37830 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
37840 20 42 4c 4f 42 20 6f 72 20 61 20 54 45 58 54 20 BLOB or a TEXT
37850 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 string, then the
37860 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
37870 62 79 74 65 73 28 29 0a 2a 2a 20 6f 72 20 73 71 bytes().** or sq
37880 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
37890 65 73 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 es16() interface
378a0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f s can be used to
378b0 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73 determine the s
378c0 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 61 74 20 42 ize.** of that B
378d0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a LOB or string..*
378e0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 *.** ^If the res
378f0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 ult is a BLOB or
37900 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 UTF-8 string th
37910 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 en the sqlite3_c
37920 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a olumn_bytes().**
37930 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
37940 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
37950 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f ytes in that BLO
37960 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 B or string..**
37970 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
37980 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e s a UTF-16 strin
37990 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f g, then sqlite3_
379a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 column_bytes() c
379b0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 onverts.** the s
379c0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 tring to UTF-8 a
379d0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 nd then returns
379e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
379f0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 tes..** ^If the
37a00 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 result is a nume
37a10 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 ric value then s
37a20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
37a30 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 tes() uses.** [s
37a40 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
37a50 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 )] to convert th
37a60 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 at value to a UT
37a70 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 F-8 string and r
37a80 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 eturns.** the nu
37a90 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
37aa0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a that string..**
37ab0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
37ac0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 is NULL, then sq
37ad0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
37ae0 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 es() returns zer
37af0 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 o..**.** ^If the
37b00 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f result is a BLO
37b10 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 B or UTF-16 stri
37b20 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 ng then the sqli
37b30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
37b40 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 16().** routine
37b50 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
37b60 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
37b70 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 hat BLOB or stri
37b80 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 ng..** ^If the r
37b90 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 esult is a UTF-8
37ba0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 string, then sq
37bb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
37bc0 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a es16() converts.
37bd0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f ** the string to
37be0 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e UTF-16 and then
37bf0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
37c00 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a ber of bytes..**
37c10 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
37c20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c is a numeric val
37c30 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ue then sqlite3_
37c40 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
37c50 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 uses.** [sqlite
37c60 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 3_snprintf()] to
37c70 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 convert that va
37c80 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 lue to a UTF-16
37c90 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 string and retur
37ca0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 ns.** the number
37cb0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 of bytes in tha
37cc0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 t string..** ^If
37cd0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e the result is N
37ce0 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 ULL, then sqlite
37cf0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
37d00 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e () returns zero.
37d10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 .**.** ^The valu
37d20 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b es returned by [
37d30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
37d40 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 ytes()] and .**
37d50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
37d60 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f bytes16()] do no
37d70 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 t include the ze
37d80 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 ro terminators a
37d90 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 t the end.** of
37da0 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f the string. ^Fo
37db0 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 r clarity: the v
37dc0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 alues returned b
37dd0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f y.** [sqlite3_co
37de0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e lumn_bytes()] an
37df0 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d [sqlite3_colum
37e00 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 n_bytes16()] are
37e10 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
37e20 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 * bytes in the s
37e30 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e tring, not the n
37e40 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 umber of charact
37e50 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 ers..**.** ^Stri
37e60 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ngs returned by
37e70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
37e80 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ext() and sqlite
37e90 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
37ea0 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 ),.** even empty
37eb0 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c strings, are al
37ec0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e ways zero-termin
37ed0 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 ated. ^The retu
37ee0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d rn.** value from
37ef0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
37f00 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 blob() for a zer
37f10 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 o-length BLOB is
37f20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
37f30 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e .**.** <b>Warnin
37f40 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 g:</b> ^The obje
37f50 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b ct returned by [
37f60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
37f70 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a alue()] is an.**
37f80 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
37f90 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
37fa0 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 ect. In a multi
37fb0 74 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e threaded environ
37fc0 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 ment,.** an unpr
37fd0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
37fe0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 value object may
37ff0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61 only be used sa
38000 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 fely with.** [sq
38010 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 lite3_bind_value
38020 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
38030 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d _result_value()]
38040 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 ..** If the [unp
38050 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
38060 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 _value] object r
38070 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
38080 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
38090 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 lue()] is used i
380a0 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c n any other way,
380b0 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 including calls
380c0 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 .** to routines
380d0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 like [sqlite3_va
380e0 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c lue_int()], [sql
380f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
38100 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 )],.** or [sqlit
38110 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 e3_value_bytes()
38120 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 ], the behavior
38130 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 is not threadsaf
38140 65 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 74 68 65 e..** Hence, the
38150 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
38160 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 value() interfac
38170 65 0a 2a 2a 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 e.** is normally
38180 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 77 69 74 only useful wit
38190 68 69 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e hin the implemen
381a0 74 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a 20 5b 61 tation of .** [a
381b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
381c0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
381d0 5d 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 ] or [virtual ta
381e0 62 6c 65 73 5d 2c 20 6e 6f 74 20 77 69 74 68 69 bles], not withi
381f0 6e 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 61 n.** top-level a
38200 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 2e pplication code.
38210 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 65 73 65 .**.** The these
38220 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 61 74 routines may at
38230 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 tempt to convert
38240 20 74 68 65 20 64 61 74 61 74 79 70 65 20 6f 66 the datatype of
38250 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 the result..**
38260 5e 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 ^For example, if
38270 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 the internal re
38280 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 presentation is
38290 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 FLOAT and a text
382a0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 result.** is re
382b0 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 quested, [sqlite
382c0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 3_snprintf()] is
382d0 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 used internally
382e0 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a to perform the.
382f0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 ** conversion au
38300 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 tomatically. ^(
38310 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 The following ta
38320 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 ble details the
38330 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 conversions.** t
38340 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a hat are applied:
38350 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
38360 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f te>.** <table bo
38370 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 rder="1">.** <tr
38380 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 ><th> Internal<b
38390 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 r>Type <th> Requ
383a0 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 ested<br>Type <t
383b0 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a h> Conversion.*
383c0 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e *.** <tr><td> N
383d0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 ULL <td> INTE
383e0 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c GER <td> Resul
383f0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 t is 0.** <tr><t
38400 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
38410 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
38420 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a Result is 0.0.**
38430 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
38440 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
38450 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
38460 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a a NULL pointer.
38470 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
38480 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 L <td> BLOB
38490 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 <td> Result
384a0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
384b0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e r.** <tr><td> IN
384c0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f TEGER <td> FLO
384d0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 AT <td> Conve
384e0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 rt from integer
384f0 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e to float.** <tr>
38500 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 <td> INTEGER <t
38510 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 d> TEXT <td
38520 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e > ASCII renderin
38530 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 g of the integer
38540 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 .** <tr><td> INT
38550 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f EGER <td> BLO
38560 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 B <td> Same a
38570 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a s INTEGER->TEXT.
38580 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f ** <tr><td> FLO
38590 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 AT <td> INTEGE
385a0 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 R <td> [CAST]
385b0 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 to INTEGER.** <t
385c0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 r><td> FLOAT
385d0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
385e0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 td> ASCII render
385f0 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 ing of the float
38600 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c .** <tr><td> FL
38610 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f OAT <td> BLO
38620 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d B <td> [CAST]
38630 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e to BLOB.** <tr>
38640 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
38650 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
38660 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 > [CAST] to INTE
38670 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 GER.** <tr><td>
38680 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 TEXT <td> F
38690 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 LOAT <td> [CA
386a0 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c ST] to REAL.** <
386b0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 tr><td> TEXT
386c0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
386d0 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a <td> No change.*
386e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
386f0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
38700 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 <td> [CAST] t
38710 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 o INTEGER.** <tr
38720 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c ><td> BLOB <
38730 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
38740 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 d> [CAST] to REA
38750 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e