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 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6940: 54 45 5f 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54 TE_OPEN_FILEPROT
6950: 45 43 54 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20 ECTION_MASK
6960: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6970: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
6980: 37 30 30 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72 700000../* Reser
6990: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 ved:
69a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
69b0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 0F00000 */../*.*
69c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 * CAPI3REF: Devi
69d0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 ce Characteristi
69e0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 cs.**.** The xDe
69f0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
6a00: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 ics method of th
6a10: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
6a20: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 thods].** object
6a30: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 returns an inte
6a40: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 ger which is a v
6a50: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a ector of these.*
6a60: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 * bit values exp
6a70: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 ressing I/O char
6a80: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 acteristics of t
6a90: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a he mass storage.
6aa0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 ** device that h
6ab0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 olds the file th
6ac0: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f at the [sqlite3_
6ad0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 io_methods].** r
6ae0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 efers to..**.**
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 20 70 72 6f 70 65 72 74 79 _ATOMIC property
6b10: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
6b20: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
6b30: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
6b40: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
6b50: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
6b60: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
6b70: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
6b80: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
6b90: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
6ba0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
6bb0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
6bc0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
6bd0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
6be0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
6bf0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
6c00: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
6c10: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
6c20: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
6c30: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
6c40: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
6c50: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
6c60: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
6c70: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
6c80: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
6c90: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
6ca0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
6cb0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
6cc0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
6cd0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
6ce0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
6cf0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
6d00: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
6d10: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
6d20: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 ite(). The SQLI
6d30: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 TE_IOCAP_POWERSA
6d40: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f FE_OVERWRITE pro
6d50: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
6d60: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 .** after reboot
6d70: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 following a cra
6d80: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 sh or power loss
6d90: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 , the only bytes
6da0: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 in a.** file th
6db0: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 at were written
6dc0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 at the applicati
6dd0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 on level might h
6de0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 ave changed.** a
6df0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 nd that adjacent
6e00: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 bytes, even byt
6e10: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 es within the sa
6e20: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a me sector are.**
6e30: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 guaranteed to b
6e40: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 e unchanged. Th
6e50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 e SQLITE_IOCAP_U
6e60: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f NDELETABLE_WHEN_
6e70: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 OPEN.** flag ind
6e80: 69 63 61 74 65 73 20 74 68 61 74 20 61 20 66 69 icates that a fi
6e90: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c le cannot be del
6ea0: 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 eted when open.
6eb0: 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 The.** SQLITE_I
6ec0: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 OCAP_IMMUTABLE f
6ed0: 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 lag indicates th
6ee0: 61 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f at the file is o
6ef0: 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d n.** read-only m
6f00: 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 edia and cannot
6f10: 62 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 be changed even
6f20: 62 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 by processes wit
6f30: 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 h.** elevated pr
6f40: 69 76 69 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 ivileges..**.**
6f50: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
6f60: 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 _BATCH_ATOMIC pr
6f70: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
6f80: 74 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 t the underlying
6f90: 0a 2a 2a 20 66 69 6c 65 73 79 73 74 65 6d 20 73 .** filesystem s
6fa0: 75 70 70 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 upports doing mu
6fb0: 6c 74 69 70 6c 65 20 77 72 69 74 65 20 6f 70 65 ltiple write ope
6fc0: 72 61 74 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c rations atomical
6fd0: 6c 79 20 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a ly when those.**
6fe0: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e write operation
6ff0: 73 20 61 72 65 20 62 72 61 63 6b 65 74 65 64 20 s are bracketed
7000: 62 79 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c by [SQLITE_FCNTL
7010: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 _BEGIN_ATOMIC_WR
7020: 49 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c ITE] and.** [SQL
7030: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 ITE_FCNTL_COMMIT
7040: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a _ATOMIC_WRITE]..
7050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
7060: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 E_IOCAP_ATOMIC
7070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
7080: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e x00000001.#defin
7090: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
70a0: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 TOMIC512
70b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
70c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
70d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 IOCAP_ATOMIC1K
70e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
70f0: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 0000004.#define
7100: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
7110: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 MIC2K
7120: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 0x00000008.#
7130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
7140: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 CAP_ATOMIC4K
7150: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
7160: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 00010.#define SQ
7170: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
7180: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C8K
7190: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 0x00000020.#de
71a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
71b0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 P_ATOMIC16K
71c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
71d0: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 040.#define SQLI
71e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 TE_IOCAP_ATOMIC3
71f0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2K
7200: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 0x00000080.#defi
7210: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
7220: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 ATOMIC64K
7230: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 0x0000010
7240: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
7250: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
7260: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 ND 0x
7270: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 00000200.#define
7280: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
7290: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 QUENTIAL
72a0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0x00000400.
72b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
72c0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 OCAP_UNDELETABLE
72d0: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 _WHEN_OPEN 0x00
72e0: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 000800.#define S
72f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 QLITE_IOCAP_POWE
7300: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 RSAFE_OVERWRITE
7310: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 0x00001000.#d
7320: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
7330: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 AP_IMMUTABLE
7340: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
7350: 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 2000.#define SQL
7360: 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f ITE_IOCAP_BATCH_
7370: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 ATOMIC
7380: 20 30 78 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 0x00004000../*.
7390: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c ** CAPI3REF: Fil
73a0: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 e Locking Levels
73b0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 .**.** SQLite us
73c0: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 es one of these
73d0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 integer values a
73e0: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 s the second.**
73f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c argument to call
7400: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 s it makes to th
7410: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 e xLock() and xU
7420: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a nlock() methods.
7430: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 ** of an [sqlite
7440: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
7450: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 ject..*/.#define
7460: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e SQLITE_LOCK_NON
7470: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 E 0.#de
7480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
7490: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 _SHARED 1
74a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
74b0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 LOCK_RESERVED
74c0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
74d0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 ITE_LOCK_PENDING
74e0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
74f0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 SQLITE_LOCK_EXC
7500: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a LUSIVE 4../*
7510: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 .** CAPI3REF: Sy
7520: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 nchronization Ty
7530: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 pe Flags.**.** W
7540: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b hen SQLite invok
7550: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d es the xSync() m
7560: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b ethod of an.** [
7570: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
7580: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 ds] object it us
7590: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e es a combination
75a0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 of.** these int
75b0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 eger values as t
75c0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
75d0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 nt..**.** When t
75e0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 he SQLITE_SYNC_D
75f0: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 ATAONLY flag is
7600: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 used, it means t
7610: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 hat the.** sync
7620: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e operation only n
7630: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 eeds to flush da
7640: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 ta to mass stora
7650: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e ge. Inode.** in
7660: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e formation need n
7670: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 ot be flushed. I
7680: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 f the lower four
7690: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 bits of the fla
76a0: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 g.** equal SQLIT
76b0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 E_SYNC_NORMAL, t
76c0: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 hat means to use
76d0: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 normal fsync()
76e0: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 semantics..** If
76f0: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 the lower four
7700: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 bits equal SQLIT
7710: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 E_SYNC_FULL, tha
7720: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 t means.** to us
7730: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 e Mac OS X style
7740: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 fullsync instea
7750: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a d of fsync()..**
7760: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 .** Do not confu
7770: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 se the SQLITE_SY
7780: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 NC_NORMAL and SQ
7790: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 LITE_SYNC_FULL f
77a0: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 lags.** with the
77b0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f [PRAGMA synchro
77c0: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 nous]=NORMAL and
77d0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f [PRAGMA synchro
77e0: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 nous]=FULL.** se
77f0: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 ttings. The [sy
7800: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 nchronous pragma
7810: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 ] determines whe
7820: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a n calls to the.*
7830: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 * xSync VFS meth
7840: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 od occur and app
7850: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 lies uniformly a
7860: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f cross all platfo
7870: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 rms..** The SQLI
7880: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 TE_SYNC_NORMAL a
7890: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 nd SQLITE_SYNC_F
78a0: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d ULL flags determ
78b0: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 ine how.** energ
78c0: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 etic or rigorous
78d0: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 or forceful the
78e0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 sync operations
78f0: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 are and.** only
7900: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e make a differen
7910: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f ce on Mac OSX fo
7920: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 r the default SQ
7930: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 Lite code..** (T
7940: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 hird-party VFS i
7950: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d mplementations m
7960: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 ight also make t
7970: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a he distinction.*
7980: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 * between SQLITE
7990: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 _SYNC_NORMAL and
79a0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
79b0: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 L, but among the
79c0: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 .** operating sy
79d0: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 stems natively s
79e0: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 upported by SQLi
79f0: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 te, only Mac OSX
7a00: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 .** cares about
7a10: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 the difference.)
7a20: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
7a30: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 TE_SYNC_NORMAL
7a40: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 0x00002.#d
7a50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e efine SQLITE_SYN
7a60: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 C_FULL
7a70: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 0x00003.#define
7a80: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 SQLITE_SYNC_DATA
7a90: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 ONLY 0x0001
7aa0: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 0../*.** CAPI3RE
7ab0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 F: OS Interface
7ac0: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 Open File Handle
7ad0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 .**.** An [sqlit
7ae0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 e3_file] object
7af0: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 represents an op
7b00: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a en file in the .
7b10: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 ** [sqlite3_vfs
7b20: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c | OS interface l
7b30: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 ayer]. Individu
7b40: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a al OS interface.
7b50: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
7b60: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 ns will.** want
7b70: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 to subclass this
7b80: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e object by appen
7b90: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 ding additional
7ba0: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 fields.** for th
7bb0: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 eir own use. Th
7bc0: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 e pMethods entry
7bd0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
7be0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f an.** [sqlite3_
7bf0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
7c00: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 ct that defines
7c10: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 methods for perf
7c20: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 orming.** I/O op
7c30: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 erations on the
7c40: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 open file..*/.ty
7c50: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
7c60: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 ite3_file sqlite
7c70: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 3_file;.struct s
7c80: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 qlite3_file {.
7c90: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c const struct sql
7ca0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 ite3_io_methods
7cb0: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d *pMethods; /* M
7cc0: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 ethods for an op
7cd0: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f en file */.};../
7ce0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
7cf0: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 S Interface File
7d00: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 Virtual Methods
7d10: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 Object.**.** Ev
7d20: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 ery file opened
7d30: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
7d40: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f vfs.xOpen] metho
7d50: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a d populates an.*
7d60: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d * [sqlite3_file]
7d70: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 object (or, mor
7d80: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 e commonly, a su
7d90: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a bclass of the.**
7da0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
7db0: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 object) with a p
7dc0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
7dd0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
7de0: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 ject..** This ob
7df0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 ject defines the
7e00: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f methods used to
7e10: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 perform various
7e20: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 operations.** a
7e30: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 gainst the open
7e40: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 file represented
7e50: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 by the [sqlite3
7e60: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a _file] object..*
7e70: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c *.** If the [sql
7e80: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 ite3_vfs.xOpen]
7e90: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 method sets the
7ea0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 sqlite3_file.pMe
7eb0: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a thods element .*
7ec0: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 * to a non-NULL
7ed0: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 pointer, then th
7ee0: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 e sqlite3_io_met
7ef0: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 hods.xClose meth
7f00: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 od.** may be inv
7f10: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 oked even if the
7f20: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f [sqlite3_vfs.xO
7f30: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 pen] reported th
7f40: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 at it failed. T
7f50: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 he.** only way t
7f60: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c o prevent a call
7f70: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f to xClose follo
7f80: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 wing a failed [s
7f90: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
7fa0: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 ].** is for the
7fb0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
7fc0: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 en] to set the s
7fd0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 qlite3_file.pMet
7fe0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 hods element.**
7ff0: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 to NULL..**.** T
8000: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
8010: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 t to xSync may b
8020: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 e one of [SQLITE
8030: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 _SYNC_NORMAL] or
8040: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 .** [SQLITE_SYNC
8050: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 _FULL]. The fir
8060: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 st choice is the
8070: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e normal fsync().
8080: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 .** The second c
8090: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f hoice is a Mac O
80a0: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 S X style fullsy
80b0: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 nc. The [SQLITE
80c0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a _SYNC_DATAONLY].
80d0: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f ** flag may be O
80e0: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 Red in to indica
80f0: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 te that only the
8100: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c data of the fil
8110: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 e.** and not its
8120: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 inode needs to
8130: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a be synced..**.**
8140: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c The integer val
8150: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 ues to xLock() a
8160: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 nd xUnlock() are
8170: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a one of.** <ul>.
8180: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8190: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c LOCK_NONE],.** <
81a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
81b0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 _SHARED],.** <li
81c0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 > [SQLITE_LOCK_R
81d0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 ESERVED],.** <li
81e0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 > [SQLITE_LOCK_P
81f0: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c ENDING], or.** <
8200: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
8210: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 _EXCLUSIVE]..**
8220: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 </ul>.** xLock()
8230: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c increases the l
8240: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 ock. xUnlock() d
8250: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 ecreases the loc
8260: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b k..** The xCheck
8270: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d ReservedLock() m
8280: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 ethod checks whe
8290: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 ther any databas
82a0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a e connection,.**
82b0: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 either in this
82c0: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f process or in so
82d0: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 me other process
82e0: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 , is holding a R
82f0: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 ESERVED,.** PEND
8300: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 ING, or EXCLUSIV
8310: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 E lock on the fi
8320: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 le. It returns
8330: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 true.** if such
8340: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e a lock exists an
8350: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 d false otherwis
8360: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 e..**.** The xFi
8370: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 leControl() meth
8380: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 od is a generic
8390: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 interface that a
83a0: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 llows custom.**
83b0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
83c0: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 ons to directly
83d0: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 control an open
83e0: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a file using the.*
83f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f * [sqlite3_file_
8400: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 control()] inter
8410: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e face. The secon
8420: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 d "op" argument
8430: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 is an.** integer
8440: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 opcode. The th
8450: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
8460: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 a generic pointe
8470: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a r intended to.**
8480: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 point to a stru
8490: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 cture that may c
84a0: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 ontain arguments
84b0: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 or space in whi
84c0: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 ch to.** write r
84d0: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 eturn values. P
84e0: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f otential uses fo
84f0: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 r xFileControl()
8500: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e might be.** fun
8510: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 ctions to enable
8520: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 blocking locks
8530: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 with timeouts, t
8540: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 o change the.**
8550: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 locking strategy
8560: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f (for example to
8570: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f use dot-file lo
8580: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 cks), to inquire
8590: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 .** about the st
85a0: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 atus of a lock,
85b0: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c or to break stal
85c0: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 e locks. The SQ
85d0: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 Lite.** core res
85e0: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 erves all opcode
85f0: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 s less than 100
8600: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e for its own use.
8610: 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 .** A [file cont
8620: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 rol opcodes | li
8630: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c st of opcodes] l
8640: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 ess than 100 is
8650: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 available..** Ap
8660: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
8670: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 define a custom
8680: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
8690: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f hod should use o
86a0: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 pcodes.** greate
86b0: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 r than 100 to av
86c0: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 oid conflicts.
86d0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
86e0: 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 ons should.** re
86f0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 turn [SQLITE_NOT
8700: 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 FOUND] for file
8710: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 control opcodes
8720: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 that they do not
8730: 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a .** recognize..*
8740: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 *.** The xSector
8750: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 Size() method re
8760: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 turns the sector
8770: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 size of the.**
8780: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 device that unde
8790: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 rlies the file.
87a0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 The sector size
87b0: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d is the.** minim
87c0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 um write that ca
87d0: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 n be performed w
87e0: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e ithout disturbin
87f0: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 g.** other bytes
8800: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 in the file. T
8810: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 he xDeviceCharac
8820: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d teristics().** m
8830: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 ethod returns a
8840: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 bit vector descr
8850: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 ibing behaviors
8860: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c of the.** underl
8870: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a ying device:.**.
8880: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
8890: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
88a0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 OMIC].** <li> [S
88b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
88c0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC512].** <li> [
88d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
88e0: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC1K].** <li> [
88f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
8900: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC2K].** <li> [
8910: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
8920: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC4K].** <li> [
8930: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
8940: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC8K].** <li> [
8950: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
8960: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC16K].** <li>
8970: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
8980: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e OMIC32K].** <li>
8990: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
89a0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 TOMIC64K].** <li
89b0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
89c0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 SAFE_APPEND].**
89d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
89e0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a AP_SEQUENTIAL].*
89f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
8a00: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 OCAP_UNDELETABLE
8a10: 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c _WHEN_OPEN].** <
8a20: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
8a30: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 P_POWERSAFE_OVER
8a40: 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b WRITE].** <li> [
8a50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d SQLITE_IOCAP_IMM
8a60: 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 UTABLE].** <li>
8a70: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 [SQLITE_IOCAP_BA
8a80: 54 43 48 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c TCH_ATOMIC].** <
8a90: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 /ul>.**.** 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 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e IC property mean
8ac0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 s that all write
8ad0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 s of.** any size
8ae0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 are atomic. Th
8af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
8b00: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a TOMICnnn values.
8b10: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 ** mean that wri
8b20: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 tes of blocks th
8b30: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 at are nnn bytes
8b40: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 in size and.**
8b50: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 are aligned to a
8b60: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 n address which
8b70: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 is an integer mu
8b80: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e ltiple of.** nnn
8b90: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 are atomic. Th
8ba0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
8bb0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 AFE_APPEND value
8bc0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 means.** that w
8bd0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 hen data is appe
8be0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 nded to a file,
8bf0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 the data is appe
8c00: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 nded.** first th
8c10: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 en the size of t
8c20: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e he file is exten
8c30: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f ded, never the o
8c40: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 ther.** way arou
8c50: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f nd. The SQLITE_
8c60: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c IOCAP_SEQUENTIAL
8c70: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 property means
8c80: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 that.** informat
8c90: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 ion is written t
8ca0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 o disk in the sa
8cb0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c me order as call
8cc0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 s.** to xWrite()
8cd0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 ..**.** If xRead
8ce0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 () returns SQLIT
8cf0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 E_IOERR_SHORT_RE
8d00: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 AD it must also
8d10: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 fill.** in the u
8d20: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f nread portions o
8d30: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 f the buffer wit
8d40: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 h zeros. A VFS
8d50: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f that.** fails to
8d60: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 zero-fill short
8d70: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 reads might see
8d80: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 m to work. Howe
8d90: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 ver,.** failure
8da0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f to zero-fill sho
8db0: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 rt reads will ev
8dc0: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f entually lead to
8dd0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 .** database cor
8de0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 ruption..*/.type
8df0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
8e00: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 e3_io_methods sq
8e10: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
8e20: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
8e30: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 _io_methods {.
8e40: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 int iVersion;.
8e50: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 int (*xClose)(sq
8e60: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
8e70: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c int (*xRead)(sql
8e80: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 ite3_file*, void
8e90: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c *, int iAmt, sql
8ea0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 ite3_int64 iOfst
8eb0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 );. int (*xWrit
8ec0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
8ed0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
8ee0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 nt iAmt, sqlite3
8ef0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 _int64 iOfst);.
8f00: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 int (*xTruncate
8f10: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
8f20: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 sqlite3_int64 s
8f30: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 ize);. int (*xS
8f40: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ync)(sqlite3_fil
8f50: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a e*, int flags);.
8f60: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a int (*xFileSiz
8f70: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
8f80: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
8f90: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 *pSize);. int (
8fa0: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f *xLock)(sqlite3_
8fb0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 file*, int);. i
8fc0: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 nt (*xUnlock)(sq
8fd0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
8fe0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 );. int (*xChec
8ff0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 kReservedLock)(s
9000: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
9010: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 t *pResOut);. i
9020: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f nt (*xFileContro
9030: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a l)(sqlite3_file*
9040: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a , int op, void *
9050: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 pArg);. int (*x
9060: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 SectorSize)(sqli
9070: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e te3_file*);. in
9080: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 t (*xDeviceChara
9090: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 cteristics)(sqli
90a0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a te3_file*);. /*
90b0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 Methods above a
90c0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 re valid for ver
90d0: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 sion 1 */. int
90e0: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 (*xShmMap)(sqlit
90f0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 e3_file*, int iP
9100: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 g, int pgsz, int
9110: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a , void volatile*
9120: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d *);. int (*xShm
9130: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 Lock)(sqlite3_fi
9140: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c le*, int offset,
9150: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 int n, int flag
9160: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 s);. void (*xSh
9170: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 mBarrier)(sqlite
9180: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 3_file*);. int
9190: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c (*xShmUnmap)(sql
91a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
91b0: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f deleteFlag);. /
91c0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 * Methods above
91d0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 are valid for ve
91e0: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 rsion 2 */. int
91f0: 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 (*xFetch)(sqlit
9200: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 e3_file*, sqlite
9210: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 3_int64 iOfst, i
9220: 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a nt iAmt, void **
9230: 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e pp);. int (*xUn
9240: 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 fetch)(sqlite3_f
9250: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ile*, sqlite3_in
9260: 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 t64 iOfst, void
9270: 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 *p);. /* Method
9280: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 s above are vali
9290: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 d for version 3
92a0: 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e */. /* Addition
92b0: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 al methods may b
92c0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
92d0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b e releases */.};
92e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
92f0: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 : Standard File
9300: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a Control Opcodes.
9310: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 ** KEYWORDS: {fi
9320: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 le control opcod
9330: 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f es} {file contro
9340: 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 l opcode}.**.**
9350: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
9360: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f nstants are opco
9370: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c des for the xFil
9380: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a eControl method.
9390: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
93a0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
93b0: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 bject and for th
93c0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f e [sqlite3_file_
93d0: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e control()].** in
93e0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c terface..**.** <
93f0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c ul>.** <li>[[SQL
9400: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 ITE_FCNTL_LOCKST
9410: 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 ATE]].** The [SQ
9420: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
9430: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 TATE] opcode is
9440: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 used for debuggi
9450: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 ng. This.** opc
9460: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 ode causes the x
9470: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
9480: 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 od to write the
9490: 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 current state of
94a0: 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e .** the lock (on
94b0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 e of [SQLITE_LOC
94c0: 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 K_NONE], [SQLITE
94d0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a _LOCK_SHARED],.*
94e0: 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 * [SQLITE_LOCK_R
94f0: 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 ESERVED], [SQLIT
9500: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c E_LOCK_PENDING],
9510: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b or [SQLITE_LOCK
9520: 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 _EXCLUSIVE]).**
9530: 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 into an integer
9540: 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 that the pArg ar
9550: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f gument points to
9560: 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 . This capabilit
9570: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 y.** is used dur
9580: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 ing testing and
9590: 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c is only availabl
95a0: 65 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 e when the SQLIT
95b0: 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c E_TEST.** compil
95c0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 e-time option is
95d0: 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 used..**.** <li
95e0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
95f0: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 SIZE_HINT]].** T
9600: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
9610: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f _SIZE_HINT] opco
9620: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 de is used by SQ
9630: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 Lite to give the
9640: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 VFS.** layer a
9650: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 hint of how larg
9660: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 e the database f
9670: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f ile will grow to
9680: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a be during the.*
9690: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 * current transa
96a0: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e ction. This hin
96b0: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 t is not guarant
96c0: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 eed to be accura
96d0: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 te but it.** is
96e0: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 often close. Th
96f0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 e underlying VFS
9700: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f might choose to
9710: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 preallocate dat
9720: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 abase.** file sp
9730: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 ace based on thi
9740: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 s hint in order
9750: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 to help writes t
9760: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a o the database.*
9770: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 * file run faste
9780: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 r..**.** <li>[[S
9790: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 QLITE_FCNTL_SIZE
97a0: 5f 4c 49 4d 49 54 5d 5d 0a 2a 2a 20 54 68 65 20 _LIMIT]].** The
97b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 [SQLITE_FCNTL_SI
97c0: 5a 45 5f 4c 49 4d 49 54 5d 20 6f 70 63 6f 64 65 ZE_LIMIT] opcode
97d0: 20 69 73 20 75 73 65 64 20 62 79 20 69 6e 2d 6d is used by in-m
97e0: 65 6d 6f 72 79 20 56 46 53 20 74 68 61 74 0a 2a emory VFS that.*
97f0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 73 20 5b 73 71 * implements [sq
9800: 6c 69 74 65 33 5f 64 65 73 65 72 69 61 6c 69 7a lite3_deserializ
9810: 65 28 29 5d 20 74 6f 20 73 65 74 20 61 6e 20 75 e()] to set an u
9820: 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 pper bound on th
9830: 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 65 e size.** of the
9840: 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 in-memory datab
9850: 61 73 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 ase. The argume
9860: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 nt is a pointer
9870: 74 6f 20 61 20 5b 73 71 6c 69 74 65 33 5f 69 6e to a [sqlite3_in
9880: 74 36 34 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 t64]..** If the
9890: 69 6e 74 65 67 65 72 20 70 6f 69 6e 74 65 64 20 integer pointed
98a0: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 to is negative,
98b0: 74 68 65 6e 20 69 74 20 69 73 20 66 69 6c 6c 65 then it is fille
98c0: 64 20 69 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a d in with the.**
98d0: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 2e 20 current limit.
98e0: 20 4f 74 68 65 72 77 69 73 65 20 74 68 65 20 6c Otherwise the l
98f0: 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20 74 imit is set to t
9900: 68 65 20 6c 61 72 67 65 72 20 6f 66 20 74 68 65 he larger of the
9910: 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 value.** of the
9920: 20 69 6e 74 65 67 65 72 20 70 6f 69 6e 74 65 64 integer pointed
9930: 20 74 6f 20 61 6e 64 20 74 68 65 20 63 75 72 72 to and the curr
9940: 65 6e 74 20 64 61 74 61 62 61 73 65 20 73 69 7a ent database siz
9950: 65 2e 20 20 54 68 65 20 69 6e 74 65 67 65 72 0a e. The integer.
9960: 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 ** pointed to is
9970: 20 73 65 74 20 74 6f 20 74 68 65 20 6e 65 77 20 set to the new
9980: 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 limit..**.** <li
9990: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
99a0: 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 CHUNK_SIZE]].**
99b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
99c0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 L_CHUNK_SIZE] op
99d0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 code is used to
99e0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65 request that the
99f0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 VFS.** extends
9a00: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 and truncates th
9a10: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
9a20: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 in chunks of a s
9a30: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a ize specified.**
9a40: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 by the user. Th
9a50: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
9a60: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 t to [sqlite3_fi
9a70: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 le_control()] sh
9a80: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 ould .** point t
9a90: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 o an integer (ty
9aa0: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 pe int) containi
9ab0: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b ng the new chunk
9ac0: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 -size to use.**
9ad0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 for the nominate
9ae0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f d database. Allo
9af0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 cating database
9b00: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 file space in la
9b10: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 rge.** chunks (s
9b20: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 ay 1MB at a time
9b30: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 ), may reduce fi
9b40: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 le-system fragme
9b50: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 ntation and.** i
9b60: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e mprove performan
9b70: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 ce on some syste
9b80: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ms..**.** <li>[[
9b90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c SQLITE_FCNTL_FIL
9ba0: 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 E_POINTER]].** T
9bb0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
9bc0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f _FILE_POINTER] o
9bd0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
9be0: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 obtain a pointe
9bf0: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c r.** to the [sql
9c00: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
9c10: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 t associated wit
9c20: 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 h a particular d
9c30: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
9c40: 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f ction. See also
9c50: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a [SQLITE_FCNTL_J
9c60: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e OURNAL_POINTER].
9c70: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
9c80: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 ITE_FCNTL_JOURNA
9c90: 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 L_POINTER]].** T
9ca0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
9cb0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 _JOURNAL_POINTER
9cc0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
9cd0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 to obtain a poi
9ce0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b nter.** to the [
9cf0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
9d00: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 ject associated
9d10: 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c with the journal
9d20: 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a file (either.**
9d30: 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a the [rollback j
9d40: 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b ournal] or the [
9d50: 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d write-ahead log]
9d60: 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c ) for a particul
9d70: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 ar database.** c
9d80: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 onnection. See
9d90: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e also [SQLITE_FCN
9da0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d TL_FILE_POINTER]
9db0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
9dc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f LITE_FCNTL_SYNC_
9dd0: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 OMITTED]].** No
9de0: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a longer in use..*
9df0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
9e00: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a E_FCNTL_SYNC]].*
9e10: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
9e20: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 NTL_SYNC] opcode
9e30: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e is generated in
9e40: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 ternally by SQLi
9e50: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 te and.** sent t
9e60: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 o the VFS immedi
9e70: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 ately before the
9e80: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 xSync method is
9e90: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a invoked on a.**
9ea0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 database file d
9eb0: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 escriptor. Or, i
9ec0: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 f the xSync meth
9ed0: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 od is not invoke
9ee0: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 d .** because th
9ef0: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 e user has confi
9f00: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 gured SQLite wit
9f10: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 h .** [PRAGMA sy
9f20: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 nchronous | PRAG
9f30: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f MA synchronous=O
9f40: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 FF] it is invoke
9f50: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f d in place .** o
9f60: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 f the xSync meth
9f70: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 od. In most case
9f80: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 s, the pointer a
9f90: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 rgument passed w
9fa0: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 ith.** this file
9fb0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c -control is NULL
9fc0: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 . However, if th
9fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
9fe0: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a is being synced.
9ff0: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 ** as part of a
a000: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 multi-database c
a010: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d ommit, the argum
a020: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 ent points to a
a030: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a nul-terminated.*
a040: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e * string contain
a050: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 ing the transact
a060: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 ions master-jour
a070: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 nal file name. V
a080: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f FSes that .** do
a090: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 not need this s
a0a0: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c ignal should sil
a0b0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 ently ignore thi
a0c0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 s opcode. Applic
a0d0: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c ations .** shoul
a0e0: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 d not call [sqli
a0f0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
a100: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 ()] with this op
a110: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f code as doing so
a120: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 may .** disrupt
a130: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f the operation o
a140: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 f the specialize
a150: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 d VFSes that do
a160: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a require it. .**
a170: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
a180: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 _FCNTL_COMMIT_PH
a190: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 ASETWO]].** The
a1a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f [SQLITE_FCNTL_CO
a1b0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f MMIT_PHASETWO] o
a1c0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 pcode is generat
a1d0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 ed internally by
a1e0: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 SQLite.** and s
a1f0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 ent to the VFS a
a200: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 fter a transacti
a210: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d on has been comm
a220: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c itted immediatel
a230: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 y.** but before
a240: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
a250: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 unlocked. VFSes
a260: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 that do not need
a270: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 this signal.**
a280: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 should silently
a290: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f ignore this opco
a2a0: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 de. Applications
a2b0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c should not call
a2c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
a2d0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 e_control()] wit
a2e0: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 h this opcode as
a2f0: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 doing so may di
a300: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 srupt the .** op
a310: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 eration of the s
a320: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 pecialized VFSes
a330: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 that do require
a340: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 it. .**.** <li
a350: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
a360: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d WIN32_AV_RETRY]]
a370: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
a380: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f _FCNTL_WIN32_AV_
a390: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 RETRY] opcode is
a3a0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 used to configu
a3b0: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 re automatic.**
a3c0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 retry counts and
a3d0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 intervals for c
a3e0: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 ertain disk I/O
a3f0: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 operations for t
a400: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 he.** windows [V
a410: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 FS] in order to
a420: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 provide robustne
a430: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e ss in the presen
a440: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 ce of.** anti-vi
a450: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 rus programs. B
a460: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 y default, the w
a470: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 indows VFS will
a480: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c retry file read,
a490: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 .** file write,
a4a0: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 and file delete
a4b0: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f operations up to
a4c0: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 10 times, with
a4d0: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 a delay.** of 25
a4e0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 milliseconds be
a4f0: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 fore the first r
a500: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 etry and with th
a510: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 e delay increasi
a520: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 ng.** by an addi
a530: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 tional 25 millis
a540: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 econds with each
a550: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 subsequent retr
a560: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f y. This.** opco
a570: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 de allows these
a580: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 two values (10 r
a590: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 etries and 25 mi
a5a0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 lliseconds of de
a5b0: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 lay).** to be ad
a5c0: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c justed. The val
a5d0: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 ues are changed
a5e0: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 for all database
a5f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 connections.**
a600: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 within the same
a610: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 process. The ar
a620: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
a630: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 ter to an array
a640: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 of two.** intege
a650: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 rs where the fir
a660: 73 74 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 st integer is th
a670: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e e new retry coun
a680: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 t and the second
a690: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 .** integer is t
a6a0: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 he delay. If ei
a6b0: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 ther integer is
a6c0: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 negative, then t
a6d0: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 he setting.** is
a6e0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 not changed but
a6f0: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 instead the pri
a700: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 or value of that
a710: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 setting is writ
a720: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 ten.** into the
a730: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c array entry, all
a740: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e owing the curren
a750: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 t retry settings
a760: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 to be.** interr
a770: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 ogated. The zDb
a780: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 Name parameter i
a790: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a s ignored..**.**
a7a0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
a7b0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d NTL_PERSIST_WAL]
a7c0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ].** ^The [SQLIT
a7d0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f E_FCNTL_PERSIST_
a7e0: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 WAL] opcode is u
a7f0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 sed to set or qu
a800: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 ery the.** persi
a810: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 stent [WAL | Wri
a820: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 te Ahead Log] se
a830: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 tting. By defau
a840: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 lt, the auxiliar
a850: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 y.** write ahead
a860: 20 6c 6f 67 20 28 5b 57 41 4c 20 66 69 6c 65 5d log ([WAL file]
a870: 29 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d ) and shared mem
a880: 6f 72 79 0a 2a 2a 20 66 69 6c 65 73 20 75 73 65 ory.** files use
a890: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f d for transactio
a8a0: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 n control.** are
a8b0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 automatically d
a8c0: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 eleted when the
a8d0: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f latest connectio
a8e0: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 n to the databas
a8f0: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 e.** closes. Se
a900: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 tting persistent
a910: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 WAL mode causes
a920: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 those files to
a930: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a persist after.**
a940: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 close. Persist
a950: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 ing the files is
a960: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 useful when oth
a970: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 er processes tha
a980: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 t do not.** have
a990: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f write permissio
a9a0: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f n on the directo
a9b0: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 ry containing th
a9c0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
a9d0: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 want.** to read
a9e0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
a9f0: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e e, as the WAL an
aa00: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 d shared memory
aa10: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 files must exist
aa20: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 .** in order for
aa30: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f the database to
aa40: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 be readable. T
aa50: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
aa60: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ter to.** [sqlit
aa70: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
aa80: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f )] for this opco
aa90: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 de should be a p
aaa0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
aab0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e eger..** That in
aac0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 teger is 0 to di
aad0: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 sable persistent
aae0: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 WAL mode or 1 t
aaf0: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 o enable persist
ab00: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e ent.** WAL mode.
ab10: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 If the integer
ab20: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 is -1, then it
ab30: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 is overwritten w
ab40: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a ith the current.
ab50: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e ** WAL persisten
ab60: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a ce setting..**.*
ab70: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
ab80: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f CNTL_POWERSAFE_O
ab90: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 VERWRITE]].** ^T
aba0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
abb0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
abc0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 RITE] opcode is
abd0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 used to set or q
abe0: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 uery the.** pers
abf0: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 istent "powersaf
ac00: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 e-overwrite" or
ac10: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 "PSOW" setting.
ac20: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e The PSOW settin
ac30: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 g.** determines
ac40: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 the [SQLITE_IOCA
ac50: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 P_POWERSAFE_OVER
ac60: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 WRITE] bit of th
ac70: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 e.** xDeviceChar
ac80: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 acteristics meth
ac90: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 ods. The fourth
aca0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
acb0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
acc0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 ntrol()] for thi
acd0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 s opcode should
ace0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 be a pointer to
acf0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 an integer..** T
ad00: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 hat integer is 0
ad10: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f to disable zero
ad20: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 -damage mode or
ad30: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 1 to enable zero
ad40: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e -damage.** mode.
ad50: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 If the integer
ad60: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 is -1, then it
ad70: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 is overwritten w
ad80: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a ith the current.
ad90: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d ** zero-damage m
ada0: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a ode setting..**.
adb0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
adc0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d FCNTL_OVERWRITE]
add0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ].** ^The [SQLIT
ade0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 E_FCNTL_OVERWRIT
adf0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 E] opcode is inv
ae00: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 oked by SQLite a
ae10: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 fter opening.**
ae20: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 a write transact
ae30: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 ion to indicate
ae40: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 that, unless it
ae50: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 is rolled back f
ae60: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f or some.** reaso
ae70: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 n, the entire da
ae80: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c tabase file will
ae90: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 be overwritten
aea0: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a by the current .
aeb0: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 ** transaction.
aec0: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 This is used by
aed0: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e VACUUM operation
aee0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 s..**.** <li>[[S
aef0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e QLITE_FCNTL_VFSN
af00: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 AME]].** ^The [S
af10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e QLITE_FCNTL_VFSN
af20: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 AME] opcode can
af30: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 be used to obtai
af40: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a n the names of.*
af50: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e * all [VFSes] in
af60: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 the VFS stack.
af70: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f The names are o
af80: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 f all VFS shims
af90: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c and the.** final
afa0: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 bottom-level VF
afb0: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e S are written in
afc0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
afd0: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c ed from .** [sql
afe0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 ite3_malloc()] a
aff0: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 nd the result is
b000: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 stored in the c
b010: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a har* variable.**
b020: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 that the fourth
b030: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 parameter of [s
b040: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
b050: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f rol()] points to
b060: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 ..** The caller
b070: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
b080: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d or freeing the m
b090: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e emory when done.
b0a0: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c As with.** all
b0b0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 file-control ac
b0c0: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 tions, there is
b0d0: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 no guarantee tha
b0e0: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 t this will actu
b0f0: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 ally.** do anyth
b100: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 ing. Callers sh
b110: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 ould initialize
b120: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 the char* variab
b130: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 le to a NULL.**
b140: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 pointer in case
b150: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f this file-contro
b160: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 l is not impleme
b170: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 nted. This file
b180: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 -control.** is i
b190: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 ntended for diag
b1a0: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e nostic use only.
b1b0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
b1c0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f ITE_FCNTL_VFS_PO
b1d0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 INTER]].** ^The
b1e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 [SQLITE_FCNTL_VF
b1f0: 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 S_POINTER] opcod
b200: 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 e finds a pointe
b210: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 r to the top-lev
b220: 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 el.** [VFSes] cu
b230: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 rrently in use.
b240: 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20 ^(The argument
b250: 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f X in.** sqlite3_
b260: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c file_control(db,
b270: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 SQLITE_FCNTL_VFS
b280: 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 _POINTER,X) must
b290: 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 be.** of type "
b2a0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a [sqlite3_vfs] **
b2b0: 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73 ". This opcodes
b2c0: 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 will set *X.**
b2d0: 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 to a pointer to
b2e0: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 the top-level VF
b2f0: 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 S.)^.** ^When th
b300: 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 ere are multiple
b310: 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68 VFS shims in th
b320: 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 e stack, this op
b330: 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a code finds the.*
b340: 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 * upper-most shi
b350: 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c m only..**.** <l
b360: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
b370: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 _PRAGMA]].** ^Wh
b380: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 enever a [PRAGMA
b390: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 ] statement is p
b3a0: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 arsed, an [SQLIT
b3b0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
b3c0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c .** file control
b3d0: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 is sent to the
b3e0: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 open [sqlite3_fi
b3f0: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 le] object corre
b400: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 sponding.** to t
b410: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
b420: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 to which the pr
b430: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 agma statement r
b440: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 efers. ^The argu
b450: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b ment.** to the [
b460: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 SQLITE_FCNTL_PRA
b470: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f GMA] file contro
b480: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 l is an array of
b490: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 .** pointers to
b4a0: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 strings (char**)
b4b0: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 in which the se
b4c0: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 cond element of
b4d0: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 the array.** is
b4e0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
b4f0: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 pragma and the t
b500: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 hird element is
b510: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 the argument to
b520: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 the.** pragma or
b530: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 NULL if the pra
b540: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d gma has no argum
b550: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c ent. ^The handl
b560: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 er for an.** [SQ
b570: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
b580: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 A] file control
b590: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d can optionally m
b5a0: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c ake the first el
b5b0: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 ement.** of the
b5c0: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 char** argument
b5d0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e point to a strin
b5e0: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 g obtained from
b5f0: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 [sqlite3_mprintf
b600: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 ()].** or the eq
b610: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 uivalent and tha
b620: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 t string will be
b630: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 come the result
b640: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 of the pragma or
b650: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 .** the error me
b660: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61 ssage if the pra
b670: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 gma fails. ^If t
b680: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 he.** [SQLITE_FC
b690: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 NTL_PRAGMA] file
b6a0: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 control returns
b6b0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e [SQLITE_NOTFOUN
b6c0: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 D], then normal
b6d0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f .** [PRAGMA] pro
b6e0: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 cessing continue
b6f0: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c s. ^If the [SQL
b700: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
b710: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f ].** file contro
b720: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 l returns [SQLIT
b730: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 E_OK], then the
b740: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 parser assumes t
b750: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 hat the.** VFS h
b760: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 as handled the P
b770: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 RAGMA itself and
b780: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 the parser gene
b790: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a rates a no-op.**
b7a0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
b7b0: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74 ent if result st
b7c0: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 ring is NULL, or
b7d0: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20 that returns a
b7e0: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 copy.** of the r
b7f0: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20 esult string if
b800: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f the string is no
b810: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 n-NULL..** ^If t
b820: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
b830: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
b840: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a ntrol returns.**
b850: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 any result code
b860: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
b870: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 ITE_OK] or [SQLI
b880: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 TE_NOTFOUND], th
b890: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 at means.** that
b8a0: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 the VFS encount
b8b0: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 ered an error wh
b8c0: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 ile handling the
b8d0: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 [PRAGMA] and th
b8e0: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e e.** compilation
b8f0: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 of the PRAGMA f
b900: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 ails with an err
b910: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 or. ^The [SQLIT
b920: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a E_FCNTL_PRAGMA].
b930: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 ** file control
b940: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65 occurs at the be
b950: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d ginning of pragm
b960: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c a statement anal
b970: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 ysis and so.** i
b980: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 t is able to ove
b990: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b rride built-in [
b9a0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e PRAGMA] statemen
b9b0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ts..**.** <li>[[
b9c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 SQLITE_FCNTL_BUS
b9d0: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 YHANDLER]].** ^T
b9e0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
b9f0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a _BUSYHANDLER].**
ba00: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 file-control ma
ba10: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 y be invoked by
ba20: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 SQLite on the da
ba30: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 tabase file hand
ba40: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 le.** shortly af
ba50: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 ter it is opened
ba60: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f in order to pro
ba70: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 vide a custom VF
ba80: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a S with access.**
ba90: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 to the connecti
baa0: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 ons busy-handler
bab0: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 callback. The a
bac0: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 rgument is of ty
bad0: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 pe (void **).**
bae0: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 - an array of tw
baf0: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 o (void *) value
bb00: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f s. The first (vo
bb10: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 id *) actually p
bb20: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 oints.** to a fu
bb30: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 nction of type (
bb40: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 int (*)(void *))
bb50: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e . In order to in
bb60: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 voke the connect
bb70: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e ions.** busy-han
bb80: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 dler, this funct
bb90: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e ion should be in
bba0: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 voked with the s
bbb0: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 econd (void *) i
bbc0: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 n.** the array a
bbd0: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d s the only argum
bbe0: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 ent. If it retur
bbf0: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
bc00: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a n the operation.
bc10: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 ** should be ret
bc20: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 ried. If it retu
bc30: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 rns zero, the cu
bc40: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 stom VFS should
bc50: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 abandon the.** c
bc60: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e urrent operation
bc70: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
bc80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 LITE_FCNTL_TEMPF
bc90: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 ILENAME]].** ^Ap
bca0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e plication can in
bcb0: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45 voke the [SQLITE
bcc0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e _FCNTL_TEMPFILEN
bcd0: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f AME] file-contro
bce0: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c l.** to have SQL
bcf0: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a ite generate a.*
bd00: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 * temporary file
bd10: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 name using the s
bd20: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 ame algorithm th
bd30: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 at is followed t
bd40: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 o generate.** te
bd50: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 mporary filename
bd60: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 s for TEMP table
bd70: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 s and other inte
bd80: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a rnal uses. The.
bd90: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 ** argument shou
bda0: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 ld be a char** w
bdb0: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c hich will be fil
bdc0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c led with the fil
bdd0: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e ename.** written
bde0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 into memory obt
bdf0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
be00: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 te3_malloc()].
be10: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c The caller shoul
be20: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c d.** invoke [sql
be30: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 ite3_free()] on
be40: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 the result to av
be50: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 oid a memory lea
be60: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 k..**.** <li>[[S
be70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 QLITE_FCNTL_MMAP
be80: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b _SIZE]].** The [
be90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 SQLITE_FCNTL_MMA
bea0: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e P_SIZE] file con
beb0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20 trol is used to
bec0: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65 query or set the
bed0: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 .** maximum numb
bee0: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74 er of bytes that
bef0: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f will be used fo
bf00: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 r memory-mapped
bf10: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 I/O..** The argu
bf20: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
bf30: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 r to a value of
bf40: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 type sqlite3_int
bf50: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 64 that.** is an
bf60: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 advisory maximu
bf70: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 m number of byte
bf80: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f s in the file to
bf90: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 memory map. Th
bfa0: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 e.** pointer is
bfb0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 overwritten with
bfc0: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 the old value.
bfd0: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f The limit is no
bfe0: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 t changed if.**
bff0: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e the value origin
c000: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 ally pointed to
c010: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 is negative, and
c020: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 so the current
c030: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 limit .** can be
c040: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73 queried by pass
c050: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 ing in a pointer
c060: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e to a negative n
c070: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 umber. This.**
c080: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 file-control is
c090: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 used internally
c0a0: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 to implement [PR
c0b0: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e AGMA mmap_size].
c0c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
c0d0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d ITE_FCNTL_TRACE]
c0e0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
c0f0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 _FCNTL_TRACE] fi
c100: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 le control provi
c110: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66 des advisory inf
c120: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 ormation.** to t
c130: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61 he VFS about wha
c140: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79 t the higher lay
c150: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74 ers of the SQLit
c160: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e e stack are doin
c170: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 g..** This file
c180: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 control is used
c190: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69 by some VFS acti
c1a0: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68 vity tracing [sh
c1b0: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 ims]..** The arg
c1c0: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d ument is a zero-
c1d0: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e terminated strin
c1e0: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72 g. Higher layer
c1f0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 s in the.** SQLi
c200: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e te stack may gen
c210: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20 erate instances
c220: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e of this file con
c230: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b trol if.** the [
c240: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c SQLITE_USE_FCNTL
c250: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d _TRACE] compile-
c260: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 time option is e
c270: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c nabled..**.** <l
c280: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
c290: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 _HAS_MOVED]].**
c2a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
c2b0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c L_HAS_MOVED] fil
c2c0: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 e control interp
c2d0: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e rets its argumen
c2e0: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 t as a.** pointe
c2f0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 r to an integer
c300: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20 and it writes a
c310: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 boolean into tha
c320: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64 t integer depend
c330: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 ing.** on whethe
c340: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c r or not the fil
c350: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d e has been renam
c360: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 ed, moved, or de
c370: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a leted since it.*
c380: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e * was first open
c390: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ed..**.** <li>[[
c3a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
c3b0: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 32_GET_HANDLE]].
c3c0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
c3d0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 CNTL_WIN32_GET_H
c3e0: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61 ANDLE] opcode ca
c3f0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 n be used to obt
c400: 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 ain the.** under
c410: 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c lying native fil
c420: 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 e handle associa
c430: 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65 20 ted with a file
c440: 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69 handle. This fi
c450: 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e le.** control in
c460: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 terprets its arg
c470: 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74 ument as a point
c480: 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66 er to a native f
c490: 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a ile handle and.*
c4a0: 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65 73 * writes the res
c4b0: 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65 ulting value the
c4c0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b re..**.** <li>[[
c4d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
c4e0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 32_SET_HANDLE]].
c4f0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
c500: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 CNTL_WIN32_SET_H
c510: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 ANDLE] opcode is
c520: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 used for debugg
c530: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 ing. This.** op
c540: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 code causes the
c550: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
c560: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20 hod to swap the
c570: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68 file handle with
c580: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e the one.** poin
c590: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41 ted to by the pA
c5a0: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 rg argument. Th
c5b0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73 is capability is
c5c0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 used during tes
c5d0: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 ting.** and only
c5e0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 needs to be sup
c5f0: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 ported when SQLI
c600: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e TE_TEST is defin
c610: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ed..**.** <li>[[
c620: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c SQLITE_FCNTL_WAL
c630: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 _BLOCK]].** The
c640: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 [SQLITE_FCNTL_WA
c650: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 L_BLOCK] is a si
c660: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20 gnal to the VFS
c670: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69 layer that it mi
c680: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 ght.** be advant
c690: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 ageous to block
c6a0: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20 on the next WAL
c6b0: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b lock if the lock
c6c0: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 is not immediat
c6d0: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 ely.** available
c6e0: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79 . The WAL subsy
c6f0: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73 stem issues this
c700: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 signal during r
c710: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 are.** circumsta
c720: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f nces in order to
c730: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 fix a problem w
c740: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76 ith priority inv
c750: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 ersion..** Appli
c760: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c cations should <
c770: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 em>not</em> use
c780: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f this file-contro
c790: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 l..**.** <li>[[S
c7a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 QLITE_FCNTL_ZIPV
c7b0: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c FS]].** The [SQL
c7c0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 ITE_FCNTL_ZIPVFS
c7d0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c ] opcode is impl
c7e0: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66 emented by zipvf
c7f0: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 s only. All othe
c800: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 r.** VFS should
c810: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f return SQLITE_NO
c820: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20 TFOUND for this
c830: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c opcode..**.** <l
c840: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
c850: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 _RBU]].** The [S
c860: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d QLITE_FCNTL_RBU]
c870: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 opcode is imple
c880: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70 mented by the sp
c890: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62 ecial VFS used b
c8a0: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74 y.** the RBU ext
c8b0: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c ension only. Al
c8c0: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75 l other VFS shou
c8d0: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 ld return SQLITE
c8e0: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a _NOTFOUND for.**
c8f0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a this opcode. .
c900: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
c910: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 TE_FCNTL_BEGIN_A
c920: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a TOMIC_WRITE]].**
c930: 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f If the [SQLITE_
c940: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d FCNTL_BEGIN_ATOM
c950: 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 IC_WRITE] opcode
c960: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
c970: 4f 4b 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 OK, then.** the
c980: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 file descriptor
c990: 69 73 20 70 6c 61 63 65 64 20 69 6e 20 22 62 61 is placed in "ba
c9a0: 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 22 2c tch write mode",
c9b0: 20 77 68 69 63 68 0a 2a 2a 20 6d 65 61 6e 73 20 which.** means
c9c0: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77 all subsequent w
c9d0: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 rite operations
c9e0: 77 69 6c 6c 20 62 65 20 64 65 66 65 72 72 65 64 will be deferred
c9f0: 20 61 6e 64 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f and done.** ato
ca00: 6d 69 63 61 6c 6c 79 20 61 74 20 74 68 65 20 6e mically at the n
ca10: 65 78 74 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 ext [SQLITE_FCNT
ca20: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f L_COMMIT_ATOMIC_
ca30: 57 52 49 54 45 5d 2e 20 20 53 79 73 74 65 6d 73 WRITE]. Systems
ca40: 0a 2a 2a 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 .** that do not
ca50: 73 75 70 70 6f 72 74 20 62 61 74 63 68 20 61 74 support batch at
ca60: 6f 6d 69 63 20 77 72 69 74 65 73 20 77 69 6c 6c omic writes will
ca70: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e return SQLITE_N
ca80: 4f 54 46 4f 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c OTFOUND..** ^Fol
ca90: 6c 6f 77 69 6e 67 20 61 20 73 75 63 63 65 73 73 lowing a success
caa0: 66 75 6c 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ful SQLITE_FCNTL
cab0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 _BEGIN_ATOMIC_WR
cac0: 49 54 45 20 61 6e 64 20 70 72 69 6f 72 20 74 6f ITE and prior to
cad0: 0a 2a 2a 20 74 68 65 20 63 6c 6f 73 69 6e 67 20 .** the closing
cae0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f [SQLITE_FCNTL_CO
caf0: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 MMIT_ATOMIC_WRIT
cb00: 45 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 E] or.** [SQLITE
cb10: 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f _FCNTL_ROLLBACK_
cb20: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2c 20 53 ATOMIC_WRITE], S
cb30: 51 4c 69 74 65 20 77 69 6c 6c 20 6d 61 6b 65 0a QLite will make.
cb40: 2a 2a 20 6e 6f 20 56 46 53 20 69 6e 74 65 72 66 ** no VFS interf
cb50: 61 63 65 20 63 61 6c 6c 73 20 6f 6e 20 74 68 65 ace calls on the
cb60: 20 73 61 6d 65 20 5b 73 71 6c 69 74 65 33 5f 66 same [sqlite3_f
cb70: 69 6c 65 5d 20 66 69 6c 65 20 64 65 73 63 72 69 ile] file descri
cb80: 70 74 6f 72 0a 2a 2a 20 65 78 63 65 70 74 20 66 ptor.** except f
cb90: 6f 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 or calls to the
cba0: 78 57 72 69 74 65 20 6d 65 74 68 6f 64 20 61 6e xWrite method an
cbb0: 64 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 d the xFileContr
cbc0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 69 74 ol method.** wit
cbd0: 68 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f h [SQLITE_FCNTL_
cbe0: 53 49 5a 45 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a SIZE_HINT]..**.*
cbf0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
cc00: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d CNTL_COMMIT_ATOM
cc10: 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 IC_WRITE]].** Th
cc20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
cc30: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 COMMIT_ATOMIC_WR
cc40: 49 54 45 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 ITE] opcode caus
cc50: 65 73 20 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 es all write.**
cc60: 6f 70 65 72 61 74 69 6f 6e 73 20 73 69 6e 63 65 operations since
cc70: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 75 the previous su
cc80: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
cc90: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e .** [SQLITE_FCN
cca0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f TL_BEGIN_ATOMIC_
ccb0: 57 52 49 54 45 5d 20 74 6f 20 62 65 20 70 65 72 WRITE] to be per
ccc0: 66 6f 72 6d 65 64 20 61 74 6f 6d 69 63 61 6c 6c formed atomicall
ccd0: 79 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 y..** This file
cce0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 control returns
ccf0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 [SQLITE_OK] if a
cd00: 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 77 nd only if the w
cd10: 72 69 74 65 73 20 77 65 72 65 0a 2a 2a 20 61 6c rites were.** al
cd20: 6c 20 70 65 72 66 6f 72 6d 65 64 20 73 75 63 63 l performed succ
cd30: 65 73 73 66 75 6c 6c 79 20 61 6e 64 20 68 61 76 essfully and hav
cd40: 65 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 e been committed
cd50: 20 74 6f 20 70 65 72 73 69 73 74 65 6e 74 20 73 to persistent s
cd60: 74 6f 72 61 67 65 2e 0a 2a 2a 20 5e 52 65 67 61 torage..** ^Rega
cd70: 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
cd80: 72 20 6f 72 20 6e 6f 74 20 69 74 20 69 73 20 73 r or not it is s
cd90: 75 63 63 65 73 73 66 75 6c 2c 20 74 68 69 73 20 uccessful, this
cda0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b file control tak
cdb0: 65 73 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 es.** the file d
cdc0: 65 73 63 72 69 70 74 6f 72 20 6f 75 74 20 6f 66 escriptor out of
cdd0: 20 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f 64 batch write mod
cde0: 65 20 73 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 e so that all su
cdf0: 62 73 65 71 75 65 6e 74 0a 2a 2a 20 77 72 69 74 bsequent.** writ
ce00: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 e operations are
ce10: 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a independent..**
ce20: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 ^SQLite will ne
ce30: 76 65 72 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54 ver invoke SQLIT
ce40: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 E_FCNTL_COMMIT_A
ce50: 54 4f 4d 49 43 5f 57 52 49 54 45 20 77 69 74 68 TOMIC_WRITE with
ce60: 6f 75 74 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 out.** a prior s
ce70: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
ce80: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f o [SQLITE_FCNTL_
ce90: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 BEGIN_ATOMIC_WRI
cea0: 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b TE]..**.** <li>[
ceb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f [SQLITE_FCNTL_RO
cec0: 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 LLBACK_ATOMIC_WR
ced0: 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 ITE]].** The [SQ
cee0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 LITE_FCNTL_ROLLB
cef0: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 ACK_ATOMIC_WRITE
cf00: 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 ] opcode causes
cf10: 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 all write.** ope
cf20: 72 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 rations since th
cf30: 65 20 70 72 65 76 69 6f 75 73 20 73 75 63 63 65 e previous succe
cf40: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a ssful call to .*
cf50: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f * [SQLITE_FCNTL_
cf60: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 BEGIN_ATOMIC_WRI
cf70: 54 45 5d 20 74 6f 20 62 65 20 72 6f 6c 6c 65 64 TE] to be rolled
cf80: 20 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20 back..** ^This
cf90: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b file control tak
cfa0: 65 73 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 es the file desc
cfb0: 72 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 riptor out of ba
cfc0: 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 0a 2a tch write mode.*
cfd0: 2a 20 73 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 * so that all su
cfe0: 62 73 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f bsequent write o
cff0: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e perations are in
d000: 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 dependent..** ^S
d010: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 QLite will never
d020: 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 invoke SQLITE_F
d030: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 CNTL_ROLLBACK_AT
d040: 4f 4d 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f OMIC_WRITE witho
d050: 75 74 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 ut.** a prior su
d060: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
d070: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 [SQLITE_FCNTL_B
d080: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 EGIN_ATOMIC_WRIT
d090: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b E]..**.** <li>[[
d0a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 SQLITE_FCNTL_LOC
d0b0: 4b 5f 54 49 4d 45 4f 55 54 5d 5d 0a 2a 2a 20 54 K_TIMEOUT]].** T
d0c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
d0d0: 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 5d 20 6f _LOCK_TIMEOUT] o
d0e0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 74 74 pcode causes att
d0f0: 65 6d 70 74 73 20 74 6f 20 6f 62 74 61 69 6e 0a empts to obtain.
d100: 2a 2a 20 61 20 66 69 6c 65 20 6c 6f 63 6b 20 75 ** a file lock u
d110: 73 69 6e 67 20 74 68 65 20 78 4c 6f 63 6b 20 6f sing the xLock o
d120: 72 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f r xShmLock metho
d130: 64 73 20 6f 66 20 74 68 65 20 56 46 53 20 74 6f ds of the VFS to
d140: 20 77 61 69 74 0a 2a 2a 20 66 6f 72 20 75 70 20 wait.** for up
d150: 74 6f 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 to M millisecond
d160: 73 20 62 65 66 6f 72 65 20 66 61 69 6c 69 6e 67 s before failing
d170: 2c 20 77 68 65 72 65 20 4d 20 69 73 20 74 68 65 , where M is the
d180: 20 73 69 6e 67 6c 65 20 0a 2a 2a 20 75 6e 73 69 single .** unsi
d190: 67 6e 65 64 20 69 6e 74 65 67 65 72 20 70 61 72 gned integer par
d1a0: 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c ameter..**.** <l
d1b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
d1c0: 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 5d 0a _DATA_VERSION]].
d1d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
d1e0: 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f CNTL_DATA_VERSIO
d1f0: 4e 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 N] opcode is use
d200: 64 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e d to detect chan
d210: 67 65 73 20 74 6f 0a 2a 2a 20 61 20 64 61 74 61 ges to.** a data
d220: 62 61 73 65 20 66 69 6c 65 2e 20 20 54 68 65 20 base file. The
d230: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f argument is a po
d240: 69 6e 74 65 72 20 74 6f 20 61 20 33 32 2d 62 69 inter to a 32-bi
d250: 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 t unsigned integ
d260: 65 72 2e 0a 2a 2a 20 54 68 65 20 22 64 61 74 61 er..** The "data
d270: 20 76 65 72 73 69 6f 6e 22 20 66 6f 72 20 74 68 version" for th
d280: 65 20 70 61 67 65 72 20 69 73 20 77 72 69 74 74 e pager is writt
d290: 65 6e 20 69 6e 74 6f 20 74 68 65 20 70 6f 69 6e en into the poin
d2a0: 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 22 64 61 ter. The.** "da
d2b0: 74 61 20 76 65 72 73 69 6f 6e 22 20 63 68 61 6e ta version" chan
d2c0: 67 65 73 20 77 68 65 6e 65 76 65 72 20 61 6e 79 ges whenever any
d2d0: 20 63 68 61 6e 67 65 20 6f 63 63 75 72 73 20 74 change occurs t
d2e0: 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 o the correspond
d2f0: 69 6e 67 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 ing.** database
d300: 66 69 6c 65 2c 20 65 69 74 68 65 72 20 74 68 72 file, either thr
d310: 6f 75 67 68 20 53 51 4c 20 73 74 61 74 65 6d 65 ough SQL stateme
d320: 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 nts on the same
d330: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
d340: 65 63 74 69 6f 6e 20 6f 72 20 74 68 72 6f 75 67 ection or throug
d350: 68 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 h transactions c
d360: 6f 6d 6d 69 74 74 65 64 20 62 79 20 73 65 70 61 ommitted by sepa
d370: 72 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a rate database.**
d380: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 70 6f 73 connections pos
d390: 73 69 62 6c 79 20 69 6e 20 6f 74 68 65 72 20 70 sibly in other p
d3a0: 72 6f 63 65 73 73 65 73 2e 20 54 68 65 20 5b 73 rocesses. The [s
d3b0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
d3c0: 6e 67 65 73 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 nges()].** inter
d3d0: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 face can be used
d3e0: 20 74 6f 20 66 69 6e 64 20 69 66 20 61 6e 79 20 to find if any
d3f0: 64 61 74 61 62 61 73 65 20 6f 6e 20 74 68 65 20 database on the
d400: 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 63 connection has c
d410: 68 61 6e 67 65 64 2c 0a 2a 2a 20 62 75 74 20 74 hanged,.** but t
d420: 68 61 74 20 69 6e 74 65 72 66 61 63 65 20 72 65 hat interface re
d430: 73 70 6f 6e 64 73 20 74 6f 20 63 68 61 6e 67 65 sponds to change
d440: 73 20 6f 6e 20 54 45 4d 50 20 61 73 20 77 65 6c s on TEMP as wel
d450: 6c 20 61 73 20 4d 41 49 4e 20 61 6e 64 20 64 6f l as MAIN and do
d460: 65 73 0a 2a 2a 20 6e 6f 74 20 70 72 6f 76 69 64 es.** not provid
d470: 65 20 61 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f e a mechanism to
d480: 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20 detect changes
d490: 74 6f 20 4d 41 49 4e 20 6f 6e 6c 79 2e 20 20 41 to MAIN only. A
d4a0: 6c 73 6f 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c lso, the.** [sql
d4b0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
d4c0: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 es()] interface
d4d0: 72 65 73 70 6f 6e 64 73 20 74 6f 20 69 6e 74 65 responds to inte
d4e0: 72 6e 61 6c 20 63 68 61 6e 67 65 73 20 6f 6e 6c rnal changes onl
d4f0: 79 20 61 6e 64 0a 2a 2a 20 6f 6d 69 74 73 20 63 y and.** omits c
d500: 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 20 6f hanges made by o
d510: 74 68 65 72 20 64 61 74 61 62 61 73 65 20 63 6f ther database co
d520: 6e 6e 65 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a nnections. The.
d530: 2a 2a 20 5b 50 52 41 47 4d 41 20 64 61 74 61 5f ** [PRAGMA data_
d540: 76 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 version] command
d550: 20 70 72 6f 76 69 64 65 20 61 20 6d 65 63 68 61 provide a mecha
d560: 6e 69 73 6d 20 74 6f 20 64 65 74 65 63 74 20 63 nism to detect c
d570: 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 61 20 73 hanges to.** a s
d580: 69 6e 67 6c 65 20 61 74 74 61 63 68 65 64 20 64 ingle attached d
d590: 61 74 61 62 61 73 65 20 74 68 61 74 20 6f 63 63 atabase that occ
d5a0: 75 72 20 64 75 65 20 74 6f 20 6f 74 68 65 72 20 ur due to other
d5b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
d5c0: 69 6f 6e 73 2c 0a 2a 2a 20 62 75 74 20 6f 6d 69 ions,.** but omi
d5d0: 74 73 20 63 68 61 6e 67 65 73 20 69 6d 70 6c 65 ts changes imple
d5e0: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 64 61 mented by the da
d5f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
d600: 6e 20 6f 6e 20 77 68 69 63 68 20 69 74 20 69 73 n on which it is
d610: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 54 68 69 .** called. Thi
d620: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 s file control i
d630: 73 20 74 68 65 20 6f 6e 6c 79 20 6d 65 63 68 61 s the only mecha
d640: 6e 69 73 6d 20 74 6f 20 64 65 74 65 63 74 20 63 nism to detect c
d650: 68 61 6e 67 65 73 20 74 68 61 74 0a 2a 2a 20 68 hanges that.** h
d660: 61 70 70 65 6e 20 65 69 74 68 65 72 20 69 6e 74 appen either int
d670: 65 72 6e 61 6c 6c 79 20 6f 72 20 65 78 74 65 72 ernally or exter
d680: 6e 61 6c 6c 79 20 61 6e 64 20 74 68 61 74 20 61 nally and that a
d690: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 re associated wi
d6a0: 74 68 0a 2a 2a 20 61 20 70 61 72 74 69 63 75 6c th.** a particul
d6b0: 61 72 20 61 74 74 61 63 68 65 64 20 64 61 74 61 ar attached data
d6c0: 62 61 73 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a base..** </ul>.*
d6d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
d6e0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
d6f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
d700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d710: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 FCNTL_GET_LOCKPR
d720: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a OXYFILE 2.
d730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
d740: 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f CNTL_SET_LOCKPRO
d750: 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 XYFILE 3.#
d760: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
d770: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 NTL_LAST_ERRNO
d780: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 4.#d
d790: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
d7a0: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 TL_SIZE_HINT
d7b0: 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 5.#de
d7c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
d7d0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 L_CHUNK_SIZE
d7e0: 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 6.#def
d7f0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
d800: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 _FILE_POINTER
d810: 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 7.#defi
d820: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
d830: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 SYNC_OMITTED
d840: 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 8.#defin
d850: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 e SQLITE_FCNTL_W
d860: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 IN32_AV_RETRY
d870: 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 9.#define
d880: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 SQLITE_FCNTL_PE
d890: 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 RSIST_WAL
d8a0: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 10.#define
d8b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 SQLITE_FCNTL_OVE
d8c0: 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 RWRITE
d8d0: 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 11.#define S
d8e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e QLITE_FCNTL_VFSN
d8f0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 AME
d900: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 12.#define SQ
d910: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 LITE_FCNTL_POWER
d920: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 SAFE_OVERWRITE
d930: 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 13.#define SQL
d940: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
d950: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
d960: 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 14.#define SQLI
d970: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e TE_FCNTL_BUSYHAN
d980: 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 DLER
d990: 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 15.#define SQLIT
d9a0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 E_FCNTL_TEMPFILE
d9b0: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 NAME 1
d9c0: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 6.#define SQLITE
d9d0: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 _FCNTL_MMAP_SIZE
d9e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 18
d9f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
da00: 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 FCNTL_TRACE
da10: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 19.
da20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
da30: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 CNTL_HAS_MOVED
da40: 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 20.#
da50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
da60: 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 NTL_SYNC
da70: 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 21.#d
da80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
da90: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 TL_COMMIT_PHASET
daa0: 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 WO 22.#de
dab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
dac0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 L_WIN32_SET_HAND
dad0: 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 LE 23.#def
dae0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
daf0: 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 _WAL_BLOCK
db00: 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 24.#defi
db10: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
db20: 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20 ZIPVFS
db30: 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 25.#defin
db40: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 e SQLITE_FCNTL_R
db50: 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20 BU
db60: 20 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65 26.#define
db70: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 SQLITE_FCNTL_VF
db80: 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 S_POINTER
db90: 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20 27.#define
dba0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 SQLITE_FCNTL_JOU
dbb0: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 RNAL_POINTER
dbc0: 20 20 20 20 32 38 0a 23 64 65 66 69 6e 65 20 53 28.#define S
dbd0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 QLITE_FCNTL_WIN3
dbe0: 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 2_GET_HANDLE
dbf0: 20 20 20 32 39 0a 23 64 65 66 69 6e 65 20 53 51 29.#define SQ
dc00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 LITE_FCNTL_PDB
dc10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
dc20: 20 20 33 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 30.#define SQL
dc30: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f ITE_FCNTL_BEGIN_
dc40: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 20 20 ATOMIC_WRITE
dc50: 20 33 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 31.#define SQLI
dc60: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f TE_FCNTL_COMMIT_
dc70: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 20 20 ATOMIC_WRITE
dc80: 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 32.#define SQLIT
dc90: 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b E_FCNTL_ROLLBACK
dca0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 33 _ATOMIC_WRITE 3
dcb0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
dcc0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 _FCNTL_LOCK_TIME
dcd0: 4f 55 54 20 20 20 20 20 20 20 20 20 20 20 33 34 OUT 34
dce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
dcf0: 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 FCNTL_DATA_VERSI
dd00: 4f 4e 20 20 20 20 20 20 20 20 20 20 20 33 35 0a ON 35.
dd10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
dd20: 43 4e 54 4c 5f 53 49 5a 45 5f 4c 49 4d 49 54 20 CNTL_SIZE_LIMIT
dd30: 20 20 20 20 20 20 20 20 20 20 20 20 33 36 0a 0a 36..
dd40: 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 /* deprecated na
dd50: 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 mes */.#define S
dd60: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 QLITE_GET_LOCKPR
dd70: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c OXYFILE SQL
dd80: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f ITE_FCNTL_GET_LO
dd90: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 CKPROXYFILE.#def
dda0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c ine SQLITE_SET_L
ddb0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 OCKPROXYFILE
ddc0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 SQLITE_FCNTL_S
ddd0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 ET_LOCKPROXYFILE
dde0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
ddf0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 LAST_ERRNO
de00: 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 SQLITE_FC
de10: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a NTL_LAST_ERRNO..
de20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
de30: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a Mutex Handle.**
de40: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f .** The mutex mo
de50: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 dule within SQLi
de60: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 te defines [sqli
de70: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 te3_mutex] to be
de80: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 an.** abstract
de90: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 type for a mutex
dea0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 object. The SQ
deb0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 Lite core never
dec0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 looks.** at the
ded0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
dee0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 ntation of an [s
def0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 qlite3_mutex].
df00: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 It only.** deals
df10: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 with pointers t
df20: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d o the [sqlite3_m
df30: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a utex] object..**
df40: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 .** Mutexes are
df50: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 created using [s
df60: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
df70: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 oc()]..*/.typede
df80: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
df90: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d _mutex sqlite3_m
dfa0: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 utex;../*.** CAP
dfb0: 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 I3REF: Loadable
dfc0: 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a Extension Thunk.
dfd0: 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 **.** A pointer
dfe0: 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73 71 to the opaque sq
dff0: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e lite3_api_routin
e000: 65 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 es structure is
e010: 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 passed as.** the
e020: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
e030: 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 to entry points
e040: 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 of [loadable ex
e050: 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 tensions]. This
e060: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d 75 .** structure mu
e070: 73 74 20 62 65 20 74 79 70 65 64 65 66 65 64 20 st be typedefed
e080: 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b in order to work
e090: 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 around compiler
e0a0: 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 warnings.** on
e0b0: 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a some platforms..
e0c0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
e0d0: 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f t sqlite3_api_ro
e0e0: 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 utines sqlite3_a
e0f0: 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a pi_routines;../*
e100: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 .** CAPI3REF: OS
e110: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 Interface Objec
e120: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 t.**.** An insta
e130: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 nce of the sqlit
e140: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 e3_vfs object de
e150: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 fines the interf
e160: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 ace between.** t
e170: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 he SQLite core a
e180: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e nd the underlyin
e190: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 g operating syst
e1a0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a em. The "vfs".*
e1b0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 * in the name of
e1c0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e the object stan
e1d0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 ds for "virtual
e1e0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 file system". S
e1f0: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c ee.** the [VFS |
e200: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 VFS documentati
e210: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 on] for further
e220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
e230: 2a 2a 20 54 68 65 20 56 46 53 20 69 6e 74 65 72 ** The VFS inter
e240: 66 61 63 65 20 69 73 20 73 6f 6d 65 74 69 6d 65 face is sometime
e250: 73 20 65 78 74 65 6e 64 65 64 20 62 79 20 61 64 s extended by ad
e260: 64 69 6e 67 20 6e 65 77 20 6d 65 74 68 6f 64 73 ding new methods
e270: 20 6f 6e 74 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 onto.** the end
e280: 2e 20 20 45 61 63 68 20 74 69 6d 65 20 73 75 63 . Each time suc
e290: 68 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6f h an extension o
e2a0: 63 63 75 72 73 2c 20 74 68 65 20 69 56 65 72 73 ccurs, the iVers
e2b0: 69 6f 6e 20 66 69 65 6c 64 0a 2a 2a 20 69 73 20 ion field.** is
e2c0: 69 6e 63 72 65 6d 65 6e 74 65 64 2e 20 20 54 68 incremented. Th
e2d0: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 e iVersion value
e2e0: 20 73 74 61 72 74 65 64 20 6f 75 74 20 61 73 20 started out as
e2f0: 31 20 69 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 1 in.** SQLite [
e300: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f version 3.5.0] o
e310: 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 35 2e 30 5d n [dateof:3.5.0]
e320: 2c 20 74 68 65 6e 20 69 6e 63 72 65 61 73 65 64 , then increased
e330: 20 74 6f 20 32 0a 2a 2a 20 77 69 74 68 20 53 51 to 2.** with SQ
e340: 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e Lite [version 3.
e350: 37 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 7.0] on [dateof:
e360: 33 2e 37 2e 30 5d 2c 20 61 6e 64 20 74 68 65 6e 3.7.0], and then
e370: 20 69 6e 63 72 65 61 73 65 64 0a 2a 2a 20 74 6f increased.** to
e380: 20 33 20 77 69 74 68 20 53 51 4c 69 74 65 20 5b 3 with SQLite [
e390: 76 65 72 73 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f version 3.7.6] o
e3a0: 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 36 5d n [dateof:3.7.6]
e3b0: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 . Additional fi
e3c0: 65 6c 64 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 elds.** may be a
e3d0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 65 20 73 ppended to the s
e3e0: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 qlite3_vfs objec
e3f0: 74 20 61 6e 64 20 74 68 65 20 69 56 65 72 73 69 t and the iVersi
e400: 6f 6e 20 76 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 on value.** may
e410: 69 6e 63 72 65 61 73 65 20 61 67 61 69 6e 20 69 increase again i
e420: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e n future version
e430: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 s of SQLite..**
e440: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74 Note that the st
e450: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 ructure.** of th
e460: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 e sqlite3_vfs ob
e470: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 ject changes in
e480: 74 68 65 20 74 72 61 6e 73 69 74 69 6f 6e 20 66 the transition f
e490: 72 6f 6d 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 rom.** SQLite [v
e4a0: 65 72 73 69 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f ersion 3.5.9] to
e4b0: 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 30 5d [version 3.6.0]
e4c0: 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 36 2e on [dateof:3.6.
e4d0: 30 5d 0a 2a 2a 20 61 6e 64 20 79 65 74 20 74 68 0].** and yet th
e4e0: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 e iVersion field
e4f0: 20 77 61 73 20 6e 6f 74 20 6d 6f 64 69 66 69 65 was not modifie
e500: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f d..**.** The szO
e510: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 sFile field is t
e520: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 he size of the s
e530: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 ubclassed [sqlit
e540: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 e3_file].** stru
e550: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 cture used by th
e560: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e is VFS. mxPathn
e570: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d ame is the maxim
e580: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 um length of.**
e590: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 a pathname in th
e5a0: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 is VFS..**.** Re
e5b0: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 gistered sqlite3
e5c0: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 _vfs objects are
e5d0: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 kept on a linke
e5e0: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 d list formed by
e5f0: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f .** the pNext po
e600: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c inter. The [sql
e610: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 ite3_vfs_registe
e620: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c r()].** and [sql
e630: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 ite3_vfs_unregis
e640: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ter()] interface
e650: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 s manage this li
e660: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 st.** in a threa
e670: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 d-safe way. The
e680: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 [sqlite3_vfs_fi
e690: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a nd()] interface.
e6a0: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 ** searches the
e6b0: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 list. Neither t
e6c0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 he application c
e6d0: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a ode nor the VFS.
e6e0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
e6f0: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 n should use the
e700: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a pNext pointer..
e710: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 **.** The pNext
e720: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c field is the onl
e730: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 y field in the s
e740: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 qlite3_vfs.** st
e750: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c ructure that SQL
e760: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f ite will ever mo
e770: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 dify. SQLite wi
e780: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a ll only access.*
e790: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 * or modify this
e7a0: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c field while hol
e7b0: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 ding a particula
e7c0: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a r static mutex..
e7d0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
e7e0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 on should never
e7f0: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 modify anything
e800: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 within the sqlit
e810: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 e3_vfs.** object
e820: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 once the object
e830: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 has been regist
e840: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ered..**.** The
e850: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 zName field hold
e860: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
e870: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 e VFS module. T
e880: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 he name must.**
e890: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 be unique across
e8a0: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 all VFS modules
e8b0: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 ..**.** [[sqlite
e8c0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 3_vfs.xOpen]].**
e8d0: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 ^SQLite guarant
e8e0: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 ees that the zFi
e8f0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
e900: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 to xOpen.** is
e910: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f either a NULL po
e920: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 inter or string
e930: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d obtained.** from
e940: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 xFullPathname()
e950: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 with an optiona
e960: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a l suffix added..
e970: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 ** ^If a suffix
e980: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 is added to the
e990: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 zFilename parame
e9a0: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 ter, it will.**
e9b0: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e consist of a sin
e9c0: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 gle "-" characte
e9d0: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f r followed by no
e9e0: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 more than.** 11
e9f0: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e alphanumeric an
ea00: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 d/or "-" charact
ea10: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ers..** ^SQLite
ea20: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 further guarante
ea30: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 es that.** the s
ea40: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 tring will be va
ea50: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 lid and unchange
ea60: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 d until xClose()
ea70: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 is.** called. B
ea80: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 ecause of the pr
ea90: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c evious sentence,
eaa0: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
eab0: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c _file] can safel
eac0: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 y store a pointe
ead0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 r to the.** file
eae0: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 name if it needs
eaf0: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 to remember the
eb00: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f filename for so
eb10: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 me reason..** If
eb20: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 the zFilename p
eb30: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 arameter to xOpe
eb40: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e n is a NULL poin
eb50: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a ter then xOpen.*
eb60: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 * must invent it
eb70: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 s own temporary
eb80: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c name for the fil
eb90: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 e. ^Whenever th
eba0: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 e .** xFilename
ebb0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c parameter is NUL
ebc0: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 L it will also b
ebd0: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 e the case that
ebe0: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 the.** flags par
ebf0: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c ameter will incl
ec00: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ude [SQLITE_OPEN
ec10: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e _DELETEONCLOSE].
ec20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 .**.** The flags
ec30: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 argument to xOp
ec40: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c en() includes al
ec50: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a l bits set in.**
ec60: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d the flags argum
ec70: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ent to [sqlite3_
ec80: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 open_v2()]. Or
ec90: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e if [sqlite3_open
eca0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 ()].** or [sqlit
ecb0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 e3_open16()] is
ecc0: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 used, then flags
ecd0: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 includes at lea
ece0: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 st.** [SQLITE_OP
ecf0: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 EN_READWRITE] |
ed00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 [SQLITE_OPEN_CRE
ed10: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 ATE]. .** If xOp
ed20: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c en() opens a fil
ed30: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e e read-only then
ed40: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c it sets *pOutFl
ed50: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 ags to.** includ
ed60: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 e [SQLITE_OPEN_R
ed70: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 EADONLY]. Other
ed80: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c bits in *pOutFl
ed90: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a ags may be set..
eda0: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 **.** ^(SQLite w
edb0: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 ill also add one
edc0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e of the followin
edd0: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 g flags to the x
ede0: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 Open().** call,
edf0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 depending on the
ee00: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 object being op
ee10: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ened:.**.** <ul>
ee20: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
ee30: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a E_OPEN_MAIN_DB].
ee40: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
ee50: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e _OPEN_MAIN_JOURN
ee60: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
ee70: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 LITE_OPEN_TEMP_D
ee80: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c B].** <li> [SQL
ee90: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f ITE_OPEN_TEMP_JO
eea0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 URNAL].** <li>
eeb0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 [SQLITE_OPEN_TRA
eec0: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c NSIENT_DB].** <l
eed0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
eee0: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 _SUBJOURNAL].**
eef0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
ef00: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 EN_MASTER_JOURNA
ef10: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
ef20: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a ITE_OPEN_WAL].**
ef30: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 </ul>)^.**.** T
ef40: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c he file I/O impl
ef50: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 ementation can u
ef60: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 se the object ty
ef70: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 pe flags to.** c
ef80: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 hange the way it
ef90: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 deals with file
efa0: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c s. For example,
efb0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a an application.
efc0: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 ** that does not
efd0: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 care about cras
efe0: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f h recovery or ro
eff0: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b llback might mak
f000: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 e.** the open of
f010: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 a journal file
f020: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 a no-op. Writes
f030: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c to this journal
f040: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 would.** also b
f050: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e e no-ops, and an
f060: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 y attempt to rea
f070: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f d the journal wo
f080: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 uld return.** SQ
f090: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 LITE_IOERR. Or
f0a0: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
f0b0: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 on might recogni
f0c0: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 ze that a databa
f0d0: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 se.** file will
f0e0: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c be doing page-al
f0f0: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 igned sector rea
f100: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e ds and writes in
f110: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 a random.** ord
f120: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 er and set up it
f130: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 s I/O subsystem
f140: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a accordingly..**.
f150: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 ** SQLite might
f160: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 also add one of
f170: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c the following fl
f180: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e ags to the xOpen
f190: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c method:.**.** <
f1a0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ul>.** <li> [SQL
f1b0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
f1c0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 NCLOSE].** <li>
f1d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 [SQLITE_OPEN_EXC
f1e0: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e LUSIVE].** </ul>
f1f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
f200: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
f210: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e CLOSE] flag mean
f220: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c s the file shoul
f230: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 d be.** deleted
f240: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 when it is close
f250: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 d. ^The [SQLITE
f260: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
f270: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 OSE].** will be
f280: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 set for TEMP dat
f290: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 abases and their
f2a0: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 journals, trans
f2b0: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 ient.** database
f2c0: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 s, and subjourna
f2d0: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b ls..**.** ^The [
f2e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
f2f0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 USIVE] flag is a
f300: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f lways used in co
f310: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 njunction.** wit
f320: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 h the [SQLITE_OP
f330: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c EN_CREATE] flag,
f340: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 which are both
f350: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c directly.** anal
f360: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 ogous to the O_E
f370: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 XCL and O_CREAT
f380: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 flags of the POS
f390: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 IX open().** API
f3a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 . The SQLITE_OP
f3b0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 EN_EXCLUSIVE fla
f3c0: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 g, when paired w
f3d0: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 ith the .** SQLI
f3e0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 TE_OPEN_CREATE,
f3f0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 is used to indic
f400: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 ate that file sh
f410: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 ould always.** b
f420: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 e created, and t
f430: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 hat it is an err
f440: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 or if it already
f450: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 exists..** It i
f460: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 s <i>not</i> use
f470: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 d to indicate th
f480: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 e file should be
f490: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 opened .** for
f4a0: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 exclusive access
f4b0: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 ..**.** ^At leas
f4c0: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 t szOsFile bytes
f4d0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 of memory are a
f4e0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 llocated by SQLi
f4f0: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 te.** to hold th
f500: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 e [sqlite3_file
f510: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 ] structure pass
f520: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a ed as the third.
f530: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 ** argument to x
f540: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e Open. The xOpen
f550: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 method does not
f560: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f have to.** allo
f570: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 cate the structu
f580: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 re; it should ju
f590: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 st fill it in.
f5a0: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 Note that.** the
f5b0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 xOpen method mu
f5c0: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 st set the sqlit
f5d0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 e3_file.pMethods
f5e0: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 to either.** a
f5f0: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 valid [sqlite3_i
f600: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
f610: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 t or to NULL. x
f620: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 Open must do.**
f630: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 this even if the
f640: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 open fails. SQ
f650: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 Lite expects tha
f660: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 t the sqlite3_fi
f670: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 le.pMethods.** e
f680: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 lement will be v
f690: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e alid after xOpen
f6a0: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c returns regardl
f6b0: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 ess of the succe
f6c0: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 ss.** or failure
f6d0: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 of the xOpen ca
f6e0: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 ll..**.** [[sqli
f6f0: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d te3_vfs.xAccess]
f700: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 ].** ^The flags
f710: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 argument to xAcc
f720: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 ess() may be [SQ
f730: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 LITE_ACCESS_EXIS
f740: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 TS].** to test f
f750: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 or the existence
f760: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b of a file, or [
f770: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
f780: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 ADWRITE] to.** t
f790: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 est whether a fi
f7a0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 le is readable a
f7b0: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 nd writable, or
f7c0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 [SQLITE_ACCESS_R
f7d0: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 EAD].** to test
f7e0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 whether a file i
f7f0: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 s at least reada
f800: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 ble. The file
f810: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 can be a.** dire
f820: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 ctory..**.** ^SQ
f830: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 Lite will always
f840: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 allocate at lea
f850: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 st mxPathname+1
f860: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a bytes for the.**
f870: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 output buffer x
f880: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 FullPathname. T
f890: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 he exact size of
f8a0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 the output buff
f8b0: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 er.** is also pa
f8c0: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 ssed as a parame
f8d0: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 ter to both met
f8e0: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 hods. If the out
f8f0: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 put buffer.** is
f900: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 not large enoug
f910: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f h, [SQLITE_CANTO
f920: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 PEN] should be r
f930: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 eturned. Since t
f940: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 his is.** handle
f950: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 d as a fatal err
f960: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 or by SQLite, vf
f970: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e s implementation
f980: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f s should endeavo
f990: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 r.** to prevent
f9a0: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 this by setting
f9b0: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 mxPathname to a
f9c0: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 sufficiently lar
f9d0: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 ge value..**.**
f9e0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 The xRandomness(
f9f0: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 ), xSleep(), xCu
fa00: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 rrentTime(), and
fa10: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 xCurrentTimeInt
fa20: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 64().** interfac
fa30: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 es are not stric
fa40: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 tly a part of th
fa50: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 e filesystem, bu
fa60: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e t they are.** in
fa70: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 cluded in the VF
fa80: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 S structure for
fa90: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a completeness..**
faa0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 The xRandomness
fab0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 () function atte
fac0: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e mpts to return n
fad0: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f Bytes bytes.** o
fae0: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 f good-quality r
faf0: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a andomness into z
fb00: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e Out. The return
fb10: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 value is.** the
fb20: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f actual number o
fb30: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f f bytes of rando
fb40: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a mness obtained..
fb50: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 ** The xSleep()
fb60: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 method causes th
fb70: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 e calling thread
fb80: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 to sleep for at
fb90: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 .** least the nu
fba0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 mber of microsec
fbb0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 onds given. ^Th
fbc0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 e xCurrentTime()
fbd0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 .** method retur
fbe0: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 ns a Julian Day
fbf0: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 Number for the c
fc00: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 urrent date and
fc10: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f time as.** a flo
fc20: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 ating point valu
fc30: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 e..** ^The xCurr
fc40: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d entTimeInt64() m
fc50: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 ethod returns, a
fc60: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 s an integer, th
fc70: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 e Julian.** Day
fc80: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 Number multiplie
fc90: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 d by 86400000 (t
fca0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c he number of mil
fcb0: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a liseconds in .**
fcc0: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e a 24-hour day).
fcd0: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 .** ^SQLite wi
fce0: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 ll use the xCurr
fcf0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d entTimeInt64() m
fd00: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 ethod to get the
fd10: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 current.** date
fd20: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 and time if tha
fd30: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 t method is avai
fd40: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 lable (if iVersi
fd50: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 on is 2 or .** g
fd60: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 reater and the f
fd70: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 unction pointer
fd80: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 is not NULL) and
fd90: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a will fall back.
fda0: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 ** to xCurrentTi
fdb0: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 me() if xCurrent
fdc0: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 TimeInt64() is u
fdd0: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a navailable..**.*
fde0: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 * ^The xSetSyste
fdf0: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 mCall(), xGetSys
fe00: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 temCall(), and x
fe10: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 NestSystemCall()
fe20: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 interfaces.** a
fe30: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 re not used by t
fe40: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 he SQLite core.
fe50: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 These optional
fe60: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 interfaces are p
fe70: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f rovided.** by so
fe80: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 me VFSes to faci
fe90: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f litate testing o
fea0: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 f the VFS code.
feb0: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a By overriding .*
fec0: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 * system calls w
fed0: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e ith functions un
fee0: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c der its control,
fef0: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 a test program
ff00: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 can.** simulate
ff10: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 faults and error
ff20: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 conditions that
ff30: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 would otherwise
ff40: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a be difficult.**
ff50: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 or impossible t
ff60: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 o induce. The s
ff70: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c et of system cal
ff80: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f ls that can be o
ff90: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 verridden.** var
ffa0: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 ies from one VFS
ffb0: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 to another, and
ffc0: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f from one versio
ffd0: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 n of the same VF
ffe0: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 S to the.** next
fff0: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 . Applications
10000 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 that use these i
10010 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 nterfaces must b
10020 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 e prepared for a
10030 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 ny.** or all of
10040 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
10050 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 to be NULL or f
10060 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f or their behavio
10070 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 r to change.** f
10080 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 rom one release
10090 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 to the next. Ap
100a0 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 plications must
100b0 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 not attempt to a
100c0 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 ccess.** any of
100d0 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 these methods if
100e0 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 the iVersion of
100f0 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 the VFS is less
10100 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 than 3..*/.type
10110 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
10120 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 e3_vfs sqlite3_v
10130 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 fs;.typedef void
10140 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 (*sqlite3_sysca
10150 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 ll_ptr)(void);.s
10160 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 truct sqlite3_vf
10170 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 s {. int iVersi
10180 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f on; /
10190 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 * Structure vers
101a0 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 ion number (curr
101b0 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e ently 3) */. in
101c0 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 t szOsFile;
101d0 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f /* Size o
101e0 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c f subclassed sql
101f0 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 ite3_file */. i
10200 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 nt mxPathname;
10210 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
10220 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 um file pathname
10230 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c length */. sql
10240 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b ite3_vfs *pNext;
10250 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 /* Next re
10260 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a gistered VFS */.
10270 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
10280 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 ame; /* Na
10290 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 me of this virtu
102a0 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a al file system *
102b0 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 /. void *pAppDa
102c0 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ta; /*
102d0 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 Pointer to appli
102e0 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 cation-specific
102f0 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a data */. int (*
10300 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 xOpen)(sqlite3_v
10310 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
10320 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f *zName, sqlite3_
10330 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 file*,.
10340 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c int flags,
10350 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 int *pOutFlags)
10360 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 ;. int (*xDelet
10370 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
10380 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
10390 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 me, int syncDir)
103a0 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 ;. int (*xAcces
103b0 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c s)(sqlite3_vfs*,
103c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
103d0 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 me, int flags, i
103e0 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 nt *pResOut);.
103f0 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e int (*xFullPathn
10400 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ame)(sqlite3_vfs
10410 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
10420 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 Name, int nOut,
10430 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 char *zOut);. v
10440 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 oid *(*xDlOpen)(
10450 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
10460 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e nst char *zFilen
10470 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 ame);. void (*x
10480 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 DlError)(sqlite3
10490 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 _vfs*, int nByte
104a0 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 , char *zErrMsg)
104b0 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c ;. void (*(*xDl
104c0 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 Sym)(sqlite3_vfs
104d0 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 *,void*, const c
104e0 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 har *zSymbol))(v
104f0 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 oid);. void (*x
10500 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 DlClose)(sqlite3
10510 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 _vfs*, void*);.
10520 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 int (*xRandomne
10530 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ss)(sqlite3_vfs*
10540 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 , int nByte, cha
10550 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 r *zOut);. int
10560 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 (*xSleep)(sqlite
10570 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 3_vfs*, int micr
10580 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 oseconds);. int
10590 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 (*xCurrentTime)
105a0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 (sqlite3_vfs*, d
105b0 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 ouble*);. int (
105c0 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 *xGetLastError)(
105d0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
105e0 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a t, char *);. /*
105f0 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 . ** The method
10600 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 s above are in v
10610 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 ersion 1 of the
10620 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 sqlite_vfs objec
10630 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f t. ** definitio
10640 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 n. Those that f
10650 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 ollow are added
10660 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 in version 2 or
10670 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 later. */. int
10680 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 (*xCurrentTimeI
10690 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 nt64)(sqlite3_vf
106a0 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 s*, sqlite3_int6
106b0 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 4*);. /*. ** T
106c0 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 he methods above
106d0 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 are in versions
106e0 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 1 and 2 of the
106f0 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 sqlite_vfs objec
10700 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 t.. ** Those be
10710 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 low are for vers
10720 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 ion 3 and greate
10730 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a r.. */. int (*
10740 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 xSetSystemCall)(
10750 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
10760 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
10770 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c sqlite3_syscall
10780 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 _ptr);. sqlite3
10790 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 _syscall_ptr (*x
107a0 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 GetSystemCall)(s
107b0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
107c0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b st char *zName);
107d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 . const char *(
107e0 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c *xNextSystemCall
107f0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
10800 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
10810 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 e);. /*. ** Th
10820 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 e methods above
10830 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 are in versions
10840 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 1 through 3 of t
10850 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 he sqlite_vfs ob
10860 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 ject.. ** New f
10870 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 ields may be app
10880 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 ended in future
10890 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 versions. The i
108a0 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c Version. ** val
108b0 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e ue will incremen
108c0 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 t whenever this
108d0 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d happens. . */.}
108e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
108f0 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 F: Flags for the
10900 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 xAccess VFS met
10910 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 hod.**.** These
10920 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
10930 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 s can be used as
10940 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
10950 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 eter to.** the x
10960 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 Access method of
10970 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 an [sqlite3_vfs
10980 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 ] object. They
10990 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 determine.** wha
109a0 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 t kind of permis
109b0 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 sions the xAcces
109c0 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b s method is look
109d0 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 ing for..** With
109e0 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 SQLITE_ACCESS_E
109f0 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 XISTS, the xAcce
10a00 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d ss method.** sim
10a10 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 ply checks wheth
10a20 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 er the file exis
10a30 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 ts..** With SQLI
10a40 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 TE_ACCESS_READWR
10a50 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 ITE, the xAccess
10a60 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b method.** check
10a70 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 s whether the na
10a80 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 med directory is
10a90 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 both readable a
10aa0 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 nd writable.** (
10ab0 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 in other words,
10ac0 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 if files can be
10ad0 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 added, removed,
10ae0 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 and renamed with
10af0 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 in.** the direct
10b00 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c ory)..** The SQL
10b10 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
10b20 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 RITE constant is
10b30 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 currently used
10b40 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b only by the.** [
10b50 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 temp_store_direc
10b60 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 tory pragma], th
10b70 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 ough this could
10b80 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 change in a futu
10b90 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 re.** release of
10ba0 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 SQLite..** With
10bb0 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
10bc0 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 EAD, the xAccess
10bd0 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b method.** check
10be0 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 s whether the fi
10bf0 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 le is readable.
10c00 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 The SQLITE_ACCE
10c10 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 SS_READ constant
10c20 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 is.** currently
10c30 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 unused, though
10c40 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 it might be used
10c50 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c in a future rel
10c60 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 ease of.** SQLit
10c70 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e..*/.#define SQ
10c80 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 LITE_ACCESS_EXIS
10c90 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 TS 0.#define
10ca0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
10cb0 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 ADWRITE 1 /* U
10cc0 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 sed by PRAGMA te
10cd0 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f mp_store_directo
10ce0 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ry */.#define SQ
10cf0 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
10d00 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 2 /* Unu
10d10 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 sed */../*.** CA
10d20 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f PI3REF: Flags fo
10d30 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 r the xShmLock V
10d40 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 FS method.**.**
10d50 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
10d60 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 nstants define t
10d70 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 he various locki
10d80 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a ng operations.**
10d90 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 allowed by the
10da0 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 xShmLock method
10db0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d of [sqlite3_io_m
10dc0 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a ethods]. The.**
10dd0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 following are t
10de0 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f he only legal co
10df0 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c mbinations of fl
10e00 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 ags to the.** xS
10e10 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a hmLock method:.*
10e20 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
10e30 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f > SQLITE_SHM_LO
10e40 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
10e50 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 SHARED.** <li>
10e60 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 SQLITE_SHM_LOCK
10e70 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 | SQLITE_SHM_EXC
10e80 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 LUSIVE.** <li>
10e90 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 SQLITE_SHM_UNLOC
10ea0 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 K | SQLITE_SHM_S
10eb0 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 HARED.** <li> S
10ec0 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b QLITE_SHM_UNLOCK
10ed0 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 | SQLITE_SHM_EX
10ee0 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e CLUSIVE.** </ul>
10ef0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f .**.** When unlo
10f00 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 cking, the same
10f10 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 SHARED or EXCLUS
10f20 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 IVE flag must be
10f30 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 supplied as.**
10f40 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 was given on the
10f50 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c corresponding l
10f60 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 ock. .**.** The
10f70 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
10f80 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 can transition
10f90 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 between unlocked
10fa0 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a and SHARED or.*
10fb0 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b * between unlock
10fc0 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 ed and EXCLUSIVE
10fd0 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 . It cannot tra
10fe0 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 nsition between
10ff0 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 SHARED.** and EX
11000 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 CLUSIVE..*/.#def
11010 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 ine SQLITE_SHM_U
11020 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 NLOCK 1.#d
11030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d efine SQLITE_SHM
11040 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a _LOCK 2.
11050 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
11060 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 HM_SHARED
11070 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
11080 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 _SHM_EXCLUSIVE
11090 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 8../*.** CAPI3
110a0 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 REF: Maximum xSh
110b0 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a mLock index.**.*
110c0 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d * The xShmLock m
110d0 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 ethod on [sqlite
110e0 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 3_io_methods] ma
110f0 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 y use values.**
11100 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 between 0 and th
11110 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 is upper bound a
11120 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 s its "offset" a
11130 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 rgument..** The
11140 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c SQLite core will
11150 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 never attempt t
11160 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c o acquire or rel
11170 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f ease a.** lock o
11180 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 utside of this r
11190 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ange.*/.#define
111a0 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b SQLITE_SHM_NLOCK
111b0 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 8.../*.*
111c0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 * CAPI3REF: Init
111d0 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 ialize The SQLit
111e0 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 e Library.**.**
111f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 ^The sqlite3_ini
11200 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e tialize() routin
11210 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 e initializes th
11220 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 e.** SQLite libr
11230 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 ary. ^The sqlit
11240 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f e3_shutdown() ro
11250 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 utine.** dealloc
11260 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 ates any resourc
11270 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c es that were all
11280 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 ocated by sqlite
11290 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 3_initialize()..
112a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
112b0 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 s are designed t
112c0 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 o aid in process
112d0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
112e0 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 and.** shutdown
112f0 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 on embedded syst
11300 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f ems. Workstatio
11310 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 n applications u
11320 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e sing.** SQLite n
11330 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e ormally do not n
11340 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 eed to invoke ei
11350 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f ther of these ro
11360 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 utines..**.** A
11370 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
11380 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
11390 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 an "effective" c
113a0 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 all if it is.**
113b0 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 the first time s
113c0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
113d0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 e() is invoked d
113e0 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 uring the lifeti
113f0 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f me of.** the pro
11400 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 cess, or if it i
11410 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 s the first time
11420 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
11430 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
11440 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 .** following a
11450 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
11460 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f shutdown(). ^(O
11470 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 nly an effective
11480 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 call.** of sqli
11490 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
114a0 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 does any initia
114b0 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f lization. All o
114c0 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 ther calls.** ar
114d0 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 e harmless no-op
114e0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c s.)^.**.** A cal
114f0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
11500 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 tdown() is an "e
11510 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 ffective" call i
11520 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 f it is the firs
11530 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c t.** call to sql
11540 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
11550 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 since the last s
11560 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
11570 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 e(). ^(Only.**
11580 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c an effective cal
11590 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
115a0 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 tdown() does any
115b0 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f deinitializatio
115c0 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 n..** All other
115d0 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 valid calls to s
115e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
115f0 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e ) are harmless n
11600 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 o-ops.)^.**.** T
11610 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 he sqlite3_initi
11620 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 alize() interfac
11630 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c e is threadsafe,
11640 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 but sqlite3_shu
11650 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f tdown().** is no
11660 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f t. The sqlite3_
11670 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 shutdown() inter
11680 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 face must only b
11690 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a e called from a.
116a0 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 ** single thread
116b0 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 . All open [dat
116c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
116d0 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 s] must be close
116e0 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 d and all.** oth
116f0 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 er SQLite resour
11700 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c ces must be deal
11710 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f located prior to
11720 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c invoking.** sql
11730 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e ite3_shutdown().
11740 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 .**.** Among oth
11750 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 er things, ^sqli
11760 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
11770 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 will invoke.**
11780 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
11790 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e ). Similarly, ^
117a0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
117b0 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b ().** will invok
117c0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 e sqlite3_os_end
117d0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ()..**.** ^The s
117e0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
117f0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 e() routine retu
11800 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 rns [SQLITE_OK]
11810 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e on success..** ^
11820 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 If for some reas
11830 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 on, sqlite3_init
11840 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 ialize() is unab
11850 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 le to initialize
11860 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 .** the library
11870 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 (perhaps it is u
11880 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
11890 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 e a needed resou
118a0 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 rce such.** as a
118b0 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 mutex) it retur
118c0 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 ns an [error cod
118d0 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 e] other than [S
118e0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a QLITE_OK]..**.**
118f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
11900 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
11910 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 ne is called int
11920 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 ernally by many
11930 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 other.** SQLite
11940 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 interfaces so th
11950 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f at an applicatio
11960 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e n usually does n
11970 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e ot need to.** in
11980 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 voke sqlite3_ini
11990 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 tialize() direct
119a0 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 ly. For example
119b0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 , [sqlite3_open(
119c0 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 )].** calls sqli
119d0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
119e0 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c so the SQLite l
119f0 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 ibrary will be a
11a00 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 utomatically.**
11a10 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e initialized when
11a20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
11a30 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 ] is called if i
11a40 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 t has not be ini
11a50 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 tialized.** alre
11a60 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 ady. ^However,
11a70 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d if SQLite is com
11a80 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b piled with the [
11a90 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f SQLITE_OMIT_AUTO
11aa0 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 INIT].** compile
11ab0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 -time option, th
11ac0 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 en the automatic
11ad0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
11ae0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 3_initialize().*
11af0 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e * are omitted an
11b00 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f d the applicatio
11b10 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 n must call sqli
11b20 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
11b30 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 directly.** pri
11b40 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 or to using any
11b50 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
11b60 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 erface. For max
11b70 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 imum portability
11b80 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d ,.** it is recom
11b90 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c mended that appl
11ba0 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 ications always
11bb0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 invoke sqlite3_i
11bc0 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 nitialize().** d
11bd0 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f irectly prior to
11be0 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 using any other
11bf0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
11c00 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 e. Future relea
11c10 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 ses.** of SQLite
11c20 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 may require thi
11c30 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 s. In other wor
11c40 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 ds, the behavior
11c50 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 exhibited.** wh
11c60 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d en SQLite is com
11c70 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 piled with [SQLI
11c80 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 TE_OMIT_AUTOINIT
11c90 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 ] might become t
11ca0 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 he.** default be
11cb0 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 havior in some f
11cc0 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 uture release of
11cd0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 SQLite..**.** T
11ce0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e he sqlite3_os_in
11cf0 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 it() routine doe
11d00 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 s operating-syst
11d10 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 em specific.** i
11d20 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 nitialization of
11d30 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
11d40 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ary. The sqlite
11d50 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 3_os_end().** ro
11d60 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 utine undoes the
11d70 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 effect of sqlit
11d80 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 e3_os_init(). T
11d90 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 ypical tasks.**
11da0 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 performed by the
11db0 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c se routines incl
11dc0 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f ude allocation o
11dd0 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a r deallocation.*
11de0 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f * of static reso
11df0 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a urces, initializ
11e00 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 ation of global
11e10 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 variables,.** se
11e20 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 tting up a defau
11e30 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d lt [sqlite3_vfs]
11e40 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 module, or sett
11e50 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 ing up.** a defa
11e60 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
11e70 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 n using [sqlite3
11e80 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a _config()]..**.*
11e90 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
11ea0 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 n should never i
11eb0 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c nvoke either sql
11ec0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a ite3_os_init().*
11ed0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f * or sqlite3_os_
11ee0 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 end() directly.
11ef0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
11f00 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 should only inv
11f10 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 oke.** sqlite3_i
11f20 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 nitialize() and
11f30 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
11f40 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 (). The sqlite3
11f50 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e _os_init().** in
11f60 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 terface is calle
11f70 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 d automatically
11f80 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 by sqlite3_initi
11f90 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 alize() and.** s
11fa0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 qlite3_os_end()
11fb0 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c is called by sql
11fc0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e ite3_shutdown().
11fd0 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a Appropriate.**
11fe0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
11ff0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f for sqlite3_os_
12000 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 init() and sqlit
12010 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 e3_os_end().** a
12020 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 re built into SQ
12030 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 Lite when it is
12040 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 compiled for Uni
12050 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f x, Windows, or O
12060 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 S/2..** When [cu
12070 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 stom builds | bu
12080 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c ilt for other pl
12090 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 atforms].** (usi
120a0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f ng the [SQLITE_O
120b0 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 S_OTHER=1] compi
120c0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f le-time.** optio
120d0 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 n) the applicati
120e0 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 on must supply a
120f0 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d suitable implem
12100 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 entation for.**
12110 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
12120 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 ) and sqlite3_os
12130 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c _end(). An appl
12140 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 ication-supplied
12150 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
12160 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 on of sqlite3_os
12170 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 _init() or sqlit
12180 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d e3_os_end().** m
12190 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ust return [SQLI
121a0 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
121b0 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 s and some other
121c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 [error code] up
121d0 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a on.** failure..*
121e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e /.int sqlite3_in
121f0 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a itialize(void);.
12200 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 int sqlite3_shut
12210 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 down(void);.int
12220 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
12230 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 void);.int sqlit
12240 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b e3_os_end(void);
12250 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
12260 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 : Configuring Th
12270 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 e SQLite Library
12280 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
12290 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 e3_config() inte
122a0 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
122b0 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e make global con
122c0 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 figuration.** ch
122d0 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 anges to SQLite
122e0 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 in order to tune
122f0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 SQLite to the s
12300 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 pecific needs of
12310 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
12320 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c ion. The defaul
12330 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 t configuration
12340 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 is recommended f
12350 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 or most.** appli
12360 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 cations and so t
12370 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 his routine is u
12380 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 sually not neces
12390 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 sary. It is.**
123a0 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 provided to supp
123b0 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 ort rare applica
123c0 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 tions with unusu
123d0 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 al needs..**.**
123e0 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 <b>The sqlite3_c
123f0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
12400 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 e is not threads
12410 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61 afe. The applica
12420 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 tion.** must ens
12430 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 ure that no othe
12440 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
12450 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 ces are invoked
12460 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 by other.** thre
12470 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 ads while sqlite
12480 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 3_config() is ru
12490 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a nning.</b>.**.**
124a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e The sqlite3_con
124b0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a fig() interface.
124c0 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 ** may only be i
124d0 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 nvoked prior to
124e0 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 library initiali
124f0 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 zation using.**
12500 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c [sqlite3_initial
12510 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 ize()] or after
12520 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c shutdown by [sql
12530 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
12540 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 ..** ^If sqlite3
12550 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c _config() is cal
12560 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 led after [sqlit
12570 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
12580 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b and before.** [
12590 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
125a0 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c ()] then it will
125b0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d return SQLITE_M
125c0 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 ISUSE..** Note,
125d0 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 however, that ^s
125e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
125f0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 can be called as
12600 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 part of the.**
12610 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
12620 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
12630 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 -defined [sqlite
12640 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 3_os_init()]..**
12650 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
12660 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
12670 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 3_config() is an
12680 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e integer.** [con
12690 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
126a0 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e n] that determin
126b0 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 es.** what prope
126c0 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 rty of SQLite is
126d0 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 to be configure
126e0 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 d. Subsequent a
126f0 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 rguments.** vary
12700 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
12710 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e e [configuration
12720 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 option].** in t
12730 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
12740 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 t..**.** ^When a
12750 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
12760 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 ption is set, sq
12770 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 lite3_config() r
12780 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
12790 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f K]..** ^If the o
127a0 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e ption is unknown
127b0 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e or SQLite is un
127c0 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 able to set the
127d0 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 option.** then t
127e0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
127f0 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b rns a non-zero [
12800 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a error code]..*/.
12810 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 int sqlite3_conf
12820 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f ig(int, ...);../
12830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
12840 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 onfigure databas
12850 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a e connections.**
12860 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
12870 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
12880 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 e3_db_config() i
12890 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
128a0 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 to make configu
128b0 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 ration.** change
128c0 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 s to a [database
128d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 connection]. T
128e0 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 he interface is
128f0 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 similar to.** [s
12900 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
12910 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 except that the
12920 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 changes apply t
12930 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 o a single.** [d
12940 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
12950 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 on] (specified i
12960 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
12970 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ment)..**.** The
12980 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
12990 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 to sqlite3_db_c
129a0 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 onfig(D,V,...)
129b0 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 is the.** [SQLIT
129c0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
129d0 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 SIDE | configura
129e0 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 tion verb] - an
129f0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a integer code .**
12a00 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 that indicates
12a10 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 what aspect of t
12a20 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
12a30 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e nection] is bein
12a40 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a g configured..**
12a50 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 Subsequent argu
12a60 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e ments vary depen
12a70 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 ding on the conf
12a80 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a iguration verb..
12a90 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 **.** ^Calls to
12aa0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
12ab0 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 g() return SQLIT
12ac0 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 E_OK if and only
12ad0 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 if.** the call
12ae0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 is considered su
12af0 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 ccessful..*/.int
12b00 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
12b10 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ig(sqlite3*, int
12b20 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a op, ...);../*.*
12b30 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f * CAPI3REF: Memo
12b40 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f ry Allocation Ro
12b50 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 utines.**.** An
12b60 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
12b70 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 object defines
12b80 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 the interface be
12b90 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 tween SQLite.**
12ba0 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 and low-level me
12bb0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
12bc0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
12bd0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 This object is u
12be0 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 sed in only one
12bf0 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c place in the SQL
12c00 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ite interface..*
12c10 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * A pointer to a
12c20 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
12c30 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 is object is the
12c40 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
12c50 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
12c60 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 )] when the conf
12c70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
12c80 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 is.** [SQLITE_C
12c90 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 ONFIG_MALLOC] or
12ca0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
12cb0 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a GETMALLOC]. .**
12cc0 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 By creating an
12cd0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
12ce0 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 object.** and p
12cf0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 assing it to [sq
12d00 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 lite3_config]([S
12d10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
12d20 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 LOC]).** during
12d30 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 configuration, a
12d40 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 n application ca
12d50 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 n specify an alt
12d60 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f ernative.** memo
12d70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 ry allocation su
12d80 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 bsystem for SQLi
12d90 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c te to use for al
12da0 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 l of its.** dyna
12db0 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 mic memory needs
12dc0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
12dd0 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 t SQLite comes w
12de0 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 ith several [bui
12df0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c lt-in memory all
12e00 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 ocators].** that
12e10 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 are perfectly a
12e20 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 dequate for the
12e30 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a overwhelming maj
12e40 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 ority of applica
12e50 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 tions.** and tha
12e60 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 t this object is
12e70 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 only useful to
12e80 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 a tiny minority
12e90 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a of applications.
12ea0 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 ** with speciali
12eb0 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 zed memory alloc
12ec0 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e ation requiremen
12ed0 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 ts. This object
12ee0 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 is.** also used
12ef0 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 during testing
12f00 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 of SQLite in ord
12f10 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e er to specify an
12f20 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 alternative.**
12f30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
12f40 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 that simulates
12f50 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 memory out-of-me
12f60 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 mory conditions
12f70 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 in.** order to v
12f80 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 erify that SQLit
12f90 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 e recovers grace
12fa0 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a fully from such.
12fb0 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a ** conditions..*
12fc0 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 *.** The xMalloc
12fd0 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 , xRealloc, and
12fe0 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 xFree methods mu
12ff0 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 st work like the
13000 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 .** malloc(), re
13010 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 alloc() and free
13020 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f () functions fro
13030 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 m the standard C
13040 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 library..** ^SQ
13050 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 Lite guarantees
13060 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 that the second
13070 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 argument to.** x
13080 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 Realloc is alway
13090 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e s a value return
130a0 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 ed by a prior ca
130b0 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a ll to xRoundup..
130c0 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 **.** xSize shou
130d0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c ld return the al
130e0 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 located size of
130f0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
13100 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c ion.** previousl
13110 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
13120 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c xMalloc or xReal
13130 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 loc. The alloca
13140 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 ted size.** is a
13150 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 lways at least a
13160 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 s big as the req
13170 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 uested size but
13180 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a may be larger..*
13190 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 *.** The xRoundu
131a0 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 p method returns
131b0 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 what would be t
131c0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
131d0 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 e of.** a memory
131e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 allocation give
131f0 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 n a particular r
13200 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 equested size.
13210 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 Most memory.** a
13220 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 llocators round
13230 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 up memory alloca
13240 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 tions at least t
13250 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 o the next multi
13260 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f ple.** of 8. So
13270 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f me allocators ro
13280 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 und up to a larg
13290 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 er multiple or t
132a0 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a o a power of 2..
132b0 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 ** Every memory
132c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 allocation reque
132d0 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 st coming in thr
132e0 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 ough [sqlite3_ma
132f0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 lloc()].** or [s
13300 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
13310 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 ] first calls xR
13320 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 oundup. If xRou
13330 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 ndup returns 0,
13340 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 .** that causes
13350 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
13360 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 g memory allocat
13370 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a ion to fail..**.
13380 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 ** The xInit met
13390 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 hod initializes
133a0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 the memory alloc
133b0 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 ator. For examp
133c0 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 le,.** it might
133d0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 allocate any req
133e0 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 uire mutexes or
133f0 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 initialize inter
13400 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 nal data.** stru
13410 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 ctures. The xSh
13420 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 utdown method is
13430 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 invoked (indire
13440 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c ctly) by.** [sql
13450 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
13460 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c and should deal
13470 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 locate any resou
13480 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a rces acquired.**
13490 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 by xInit. The
134a0 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 pAppData pointer
134b0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 is used as the
134c0 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 only parameter t
134d0 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 o.** xInit and x
134e0 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 Shutdown..**.**
134f0 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 SQLite holds the
13500 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 [SQLITE_MUTEX_S
13510 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 TATIC_MASTER] mu
13520 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f tex when it invo
13530 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 kes.** the xInit
13540 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 method, so the
13550 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 xInit method nee
13560 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 d not be threads
13570 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 afe. The.** xSh
13580 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 utdown method is
13590 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f only called fro
135a0 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 m [sqlite3_shutd
135b0 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 own()] so it doe
135c0 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f s.** not need to
135d0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 be threadsafe e
135e0 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 ither. For all
135f0 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 other methods, S
13600 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 QLite.** holds t
13610 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 he [SQLITE_MUTEX
13620 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 _STATIC_MEM] mut
13630 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 ex as long as th
13640 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e e.** [SQLITE_CON
13650 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 FIG_MEMSTATUS] c
13660 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
13670 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e ion is turned on
13680 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 (which.** it is
13690 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 by default) and
136a0 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 so the methods
136b0 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c are automaticall
136c0 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a y serialized..**
136d0 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 However, if [SQ
136e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
136f0 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c TATUS] is disabl
13700 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 ed, then the oth
13710 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 er.** methods mu
13720 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 st be threadsafe
13730 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 or else make th
13740 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d eir own arrangem
13750 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 ents for.** seri
13760 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a alization..**.**
13770 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 SQLite will nev
13780 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 er invoke xInit(
13790 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 ) more than once
137a0 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 without an inte
137b0 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 rvening.** call
137c0 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a to xShutdown()..
137d0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
137e0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 t sqlite3_mem_me
137f0 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 thods sqlite3_me
13800 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 m_methods;.struc
13810 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 t sqlite3_mem_me
13820 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a thods {. void *
13830 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b (*xMalloc)(int);
13840 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f /* Memo
13850 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 ry allocation fu
13860 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 nction */. void
13870 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 (*xFree)(void*)
13880 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 ; /* Fr
13890 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 ee a prior alloc
138a0 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 ation */. void
138b0 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 *(*xRealloc)(voi
138c0 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 d*,int); /* Res
138d0 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f ize an allocatio
138e0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 n */. int (*xSi
138f0 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 ze)(void*);
13900 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 /* Return
13910 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 the size of an a
13920 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 llocation */. i
13930 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 nt (*xRoundup)(i
13940 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a nt); /*
13950 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 Round up reques
13960 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 t size to alloca
13970 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 tion size */. i
13980 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 nt (*xInit)(void
13990 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a *); /*
139a0 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 Initialize the
139b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
139c0 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 */. void (*xSh
139d0 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 utdown)(void*);
139e0 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 /* Deinitia
139f0 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 lize the memory
13a00 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 allocator */. v
13a10 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 oid *pAppData;
13a20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
13a30 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e Argument to xIn
13a40 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f it() and xShutdo
13a50 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a wn() */.};../*.*
13a60 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
13a70 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e iguration Option
13a80 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
13a90 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
13aa0 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tion}.**.** Thes
13ab0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
13ac0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e the available in
13ad0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 teger configurat
13ae0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 ion options that
13af0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 .** can be passe
13b00 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 d as the first a
13b10 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b rgument to the [
13b20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
13b30 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a ] interface..**.
13b40 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 ** New configura
13b50 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 tion options may
13b60 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
13b70 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
13b80 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 SQLite..** Exist
13b90 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ing configuratio
13ba0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 n options might
13bb0 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e be discontinued.
13bc0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a Applications.*
13bd0 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 * should check t
13be0 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 he return code f
13bf0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e rom [sqlite3_con
13c00 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 fig()] to make s
13c10 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ure that.** the
13c20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 call worked. Th
13c30 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 e [sqlite3_confi
13c40 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 g()] interface w
13c50 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 ill return a.**
13c60 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 non-zero [error
13c70 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f code] if a disco
13c80 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 ntinued or unsup
13c90 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 ported configura
13ca0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 tion option.** i
13cb0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a s invoked..**.**
13cc0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 <dl>.** [[SQLIT
13cd0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
13ce0 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 HREAD]] <dt>SQLI
13cf0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
13d00 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c THREAD</dt>.** <
13d10 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 dd>There are no
13d20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 arguments to thi
13d30 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 s option. ^This
13d40 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 option sets the
13d50 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d .** [threading m
13d60 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 ode] to Single-t
13d70 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 hread. In other
13d80 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 words, it disab
13d90 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 les.** all mutex
13da0 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c ing and puts SQL
13db0 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 ite into a mode
13dc0 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c where it can onl
13dd0 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 y be used.** by
13de0 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e a single thread.
13df0 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 ^If SQLite is
13e00 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
13e10 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 * the [SQLITE_TH
13e20 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 READSAFE | SQLIT
13e30 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
13e40 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
13e50 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 ion then.** it i
13e60 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 s not possible t
13e70 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 o change the [th
13e80 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 reading mode] fr
13e90 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a om its default.*
13ea0 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c * value of Singl
13eb0 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 e-thread and so
13ec0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
13ed0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a )] will return .
13ee0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ** [SQLITE_ERROR
13ef0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 ] if called with
13f00 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 the SQLITE_CONF
13f10 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a IG_SINGLETHREAD.
13f20 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ** configuration
13f30 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a option.</dd>.**
13f40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
13f50 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d FIG_MULTITHREAD]
13f60 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
13f70 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c FIG_MULTITHREAD<
13f80 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 /dt>.** <dd>Ther
13f90 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e e are no argumen
13fa0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f ts to this optio
13fb0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e n. ^This option
13fc0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 sets the.** [th
13fd0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f reading mode] to
13fe0 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 Multi-thread.
13ff0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
14000 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d it disables.** m
14010 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 utexing on [data
14020 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
14030 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
14040 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 tatement] object
14050 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 s..** The applic
14060 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 ation is respons
14070 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 ible for seriali
14080 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a zing access to.*
14090 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
140a0 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 ections] and [pr
140b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
140c0 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d s]. But other m
140d0 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e utexes.** are en
140e0 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 abled so that SQ
140f0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 Lite will be saf
14100 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 e to use in a mu
14110 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 lti-threaded.**
14120 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c environment as l
14130 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 ong as no two th
14140 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f reads attempt to
14150 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a use the same.**
14160 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
14170 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 ction] at the sa
14180 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 me time. ^If SQ
14190 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
141a0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 with.** the [SQ
141b0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 LITE_THREADSAFE
141c0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 | SQLITE_THREADS
141d0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 AFE=0] compile-t
141e0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a ime option then.
141f0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 ** it is not pos
14200 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 sible to set the
14210 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 Multi-thread [t
14220 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 hreading mode] a
14230 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 nd.** [sqlite3_c
14240 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 onfig()] will re
14250 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 turn [SQLITE_ERR
14260 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 OR] if called wi
14270 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 th the.** SQLITE
14280 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
14290 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f EAD configuratio
142a0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a n option.</dd>.*
142b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
142c0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d NFIG_SERIALIZED]
142d0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
142e0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f FIG_SERIALIZED</
142f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 dt>.** <dd>There
14300 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 are no argument
14310 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
14320 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 . ^This option
14330 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 sets the.** [thr
14340 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 eading mode] to
14350 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f Serialized. In o
14360 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 ther words, this
14370 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a option enables.
14380 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 ** all mutexes i
14390 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 ncluding the rec
143a0 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 ursive.** mutexe
143b0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 s on [database c
143c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b onnection] and [
143d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
143e0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 nt] objects..**
143f0 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 In this mode (wh
14400 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 ich is the defau
14410 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 lt when SQLite i
14420 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
14430 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 ** [SQLITE_THREA
14440 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 DSAFE=1]) the SQ
14450 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c Lite library wil
14460 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 l itself seriali
14470 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 ze access.** to
14480 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
14490 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 tions] and [prep
144a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
144b0 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 so that the.**
144c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 application is f
144d0 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 ree to use the s
144e0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f ame [database co
144f0 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 nnection] or the
14500 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 .** same [prepar
14510 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e ed statement] in
14520 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
14530 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 ds at the same t
14540 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 ime..** ^If SQLi
14550 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
14560 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
14570 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
14580 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
14590 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
145a0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
145b0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 it is not possi
145c0 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 ble to set the S
145d0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 erialized [threa
145e0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a ding mode] and.*
145f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
14600 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e g()] will return
14610 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
14620 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 if called with t
14630 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e he.** SQLITE_CON
14640 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 FIG_SERIALIZED c
14650 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
14660 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ion.</dd>.**.**
14670 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
14680 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c MALLOC]] <dt>SQL
14690 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
146a0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e C</dt>.** <dd> ^
146b0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
146c0 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e IG_MALLOC option
146d0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
146e0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
146f0 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 s .** a pointer
14700 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
14710 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
14720 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
14730 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 cture..** The ar
14740 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 gument specifies
14750 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 .** alternative
14760 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 low-level memory
14770 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
14780 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 ines to be used
14790 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 in place of.** t
147a0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
147b0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 tion routines bu
147c0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e ilt into SQLite.
147d0 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 )^ ^SQLite makes
147e0 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 .** its own priv
147f0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ate copy of the
14800 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b content of the [
14810 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
14820 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a ods] structure.*
14830 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 * before the [sq
14840 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
14850 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 call returns.</d
14860 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
14870 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
14880 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f OC]] <dt>SQLITE_
14890 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
148a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
148b0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
148c0 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 G_GETMALLOC opti
148d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
148e0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
148f0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 .** is a pointer
14900 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
14910 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
14920 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 mem_methods] str
14930 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b ucture..** The [
14940 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
14950 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 ods].** structur
14960 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 e is filled with
14970 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 the currently d
14980 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c efined memory al
14990 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
149a0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 s.)^.** This opt
149b0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 ion can be used
149c0 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 to overload the
149d0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 default memory a
149e0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 llocation.** rou
149f0 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 tines with a wra
14a00 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 pper that simula
14a10 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c tions memory all
14a20 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 ocation failure
14a30 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d or.** tracks mem
14a40 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 ory usage, for e
14a50 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a xample. </dd>.**
14a60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
14a70 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 FIG_SMALL_MALLOC
14a80 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
14a90 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f NFIG_SMALL_MALLO
14aa0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e C</dt>.** <dd> ^
14ab0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
14ac0 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f G_SMALL_MALLOC o
14ad0 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 ption takes sing
14ae0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 0a 2a le argument of.*
14af0 2a 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 * type int, inte
14b00 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f rpreted as a boo
14b10 6c 65 61 6e 2c 20 77 68 69 63 68 20 69 66 20 74 lean, which if t
14b20 72 75 65 20 70 72 6f 76 69 64 65 73 20 61 20 68 rue provides a h
14b30 69 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 int to.** SQLite
14b40 20 74 68 61 74 20 69 74 20 73 68 6f 75 6c 64 20 that it should
14b50 61 76 6f 69 64 20 6c 61 72 67 65 20 6d 65 6d 6f avoid large memo
14b60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 69 ry allocations i
14b70 66 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 53 f possible..** S
14b80 51 4c 69 74 65 20 77 69 6c 6c 20 72 75 6e 20 66 QLite will run f
14b90 61 73 74 65 72 20 69 66 20 69 74 20 69 73 20 66 aster if it is f
14ba0 72 65 65 20 74 6f 20 6d 61 6b 65 20 6c 61 72 67 ree to make larg
14bb0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
14bc0 69 6f 6e 73 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d ions,.** but som
14bd0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 e application mi
14be0 67 68 74 20 70 72 65 66 65 72 20 74 6f 20 72 75 ght prefer to ru
14bf0 6e 20 73 6c 6f 77 65 72 20 69 6e 20 65 78 63 68 n slower in exch
14c00 61 6e 67 65 20 66 6f 72 0a 2a 2a 20 67 75 61 72 ange for.** guar
14c10 61 6e 74 65 65 73 20 61 62 6f 75 74 20 6d 65 6d antees about mem
14c20 6f 72 79 20 66 72 61 67 6d 65 6e 74 61 74 69 6f ory fragmentatio
14c30 6e 20 74 68 61 74 20 61 72 65 20 70 6f 73 73 69 n that are possi
14c40 62 6c 65 20 69 66 20 6c 61 72 67 65 0a 2a 2a 20 ble if large.**
14c50 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 72 65 20 allocations are
14c60 61 76 6f 69 64 65 64 2e 20 20 54 68 69 73 20 68 avoided. This h
14c70 69 6e 74 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 int is normally
14c80 6f 66 66 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a off..** </dd>.**
14c90 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
14ca0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 FIG_MEMSTATUS]]
14cb0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
14cc0 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e G_MEMSTATUS</dt>
14cd0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 .** <dd> ^The SQ
14ce0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
14cf0 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b TATUS option tak
14d00 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 es single argume
14d10 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a nt of type int,.
14d20 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 ** interpreted a
14d30 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 s a boolean, whi
14d40 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ch enables or di
14d50 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 sables the colle
14d60 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f ction of.** memo
14d70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 ry allocation st
14d80 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e atistics. ^(When
14d90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
14da0 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 on statistics ar
14db0 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 e.** disabled, t
14dc0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c he following SQL
14dd0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 ite interfaces b
14de0 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 ecome non-operat
14df0 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e ional:.** <ul>
14e00 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 .** <li> [sqli
14e10 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
14e20 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
14e30 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
14e40 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c hwater()].** <
14e50 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 li> [sqlite3_sof
14e60 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 t_heap_limit64()
14e70 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
14e80 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d ite3_status64()]
14e90 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a .** </ul>)^.**
14ea0 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 ^Memory allocat
14eb0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 ion statistics a
14ec0 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 re enabled by de
14ed0 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c fault unless SQL
14ee0 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c ite is.** compil
14ef0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f ed with [SQLITE_
14f00 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 DEFAULT_MEMSTATU
14f10 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 S]=0 in which ca
14f20 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c se memory.** all
14f30 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 ocation statisti
14f40 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 cs are disabled
14f50 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c by default..** <
14f60 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
14f70 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
14f80 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f CH]] <dt>SQLITE_
14f90 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f CONFIG_SCRATCH</
14fa0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 dt>.** <dd> The
14fb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
14fc0 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 69 73 20 RATCH option is
14fd0 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 2e 0a no longer used..
14fe0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ** </dd>.**.** [
14ff0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
15000 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 AGECACHE]] <dt>S
15010 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
15020 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c ECACHE</dt>.** <
15030 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f dd> ^The SQLITE_
15040 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
15050 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 option specifie
15060 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a s a memory pool.
15070 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 ** that SQLite c
15080 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 an use for the d
15090 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 atabase page cac
150a0 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 he with the defa
150b0 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 ult page.** cach
150c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
150d0 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 . .** This conf
150e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
150f0 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 is a no-op if a
15100 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
15110 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 fine page.** cac
15120 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
15130 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e n is loaded usin
15140 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f g the [SQLITE_CO
15150 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a NFIG_PCACHE2]..*
15160 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 * ^There are thr
15170 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 ee arguments to
15180 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
15190 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 GECACHE: A point
151a0 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 er to.** 8-byte
151b0 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 aligned memory (
151c0 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 pMem), the size
151d0 6f 66 20 65 61 63 68 20 70 61 67 65 20 63 61 63 of each page cac
151e0 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a he line (sz),.**
151f0 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 and the number
15200 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28 of cache lines (
15210 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 N)..** The sz ar
15220 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 gument should be
15230 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
15240 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 largest databas
15250 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 e page.** (a pow
15260 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 er of two betwee
15270 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29 n 512 and 65536)
15280 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61 plus some extra
15290 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a bytes for each.
152a0 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 ** page header.
152b0 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 ^The number of
152c0 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64 extra bytes need
152d0 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68 ed by the page h
152e0 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 eader.** can be
152f0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 determined using
15300 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
15310 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a PCACHE_HDRSZ]..*
15320 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 * ^It is harmles
15330 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 s, apart from th
15340 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c e wasted memory,
15350 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 .** for the sz p
15360 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c arameter to be l
15370 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 arger than neces
15380 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a sary. The pMem.
15390 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 ** argument must
153a0 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c be either a NUL
153b0 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 L pointer or a p
153c0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 ointer to an 8-b
153d0 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 yte.** aligned b
153e0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f lock of memory o
153f0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 f at least sz*N
15400 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65 bytes, otherwise
15410 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62 .** subsequent b
15420 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
15430 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 ined..** ^When p
15440 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c Mem is not NULL,
15450 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 SQLite will str
15460 69 76 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d ive to use the m
15470 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a emory provided.*
15480 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70 61 67 * to satisfy pag
15490 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66 e cache needs, f
154a0 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b alling back to [
154b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
154c0 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 ] if.** a page c
154d0 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 ache line is lar
154e0 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65 ger than sz byte
154f0 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 s or if all of t
15500 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a he pMem buffer.*
15510 2a 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a * is exhausted..
15520 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e ** ^If pMem is N
15530 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e ULL and N is non
15540 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 -zero, then each
15550 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
15560 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 tion.** does an
15570 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c initial bulk all
15580 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 ocation for page
15590 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a cache memory.**
155a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
155b0 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69 alloc()] suffici
155c0 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20 ent for N cache
155d0 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f lines if N is po
155e0 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 sitive or.** of
155f0 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66 -1024*N bytes if
15600 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 N is negative,
15610 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c . ^If additional
15620 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d .** page cache m
15630 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 emory is needed
15640 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 beyond what is p
15650 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 69 rovided by the i
15660 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 nitial.** alloca
15670 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 tion, then SQLit
15680 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 e goes to [sqlit
15690 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 e3_malloc()] sep
156a0 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68 arately for each
156b0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 .** additional c
156c0 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e ache line. </dd>
156d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
156e0 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 CONFIG_HEAP]] <d
156f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
15700 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 HEAP</dt>.** <dd
15710 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f > ^The SQLITE_CO
15720 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e NFIG_HEAP option
15730 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 specifies a sta
15740 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 tic memory buffe
15750 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 r .** that SQLit
15760 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 e will use for a
15770 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 ll of its dynami
15780 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 c memory allocat
15790 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 ion needs.** bey
157a0 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 ond those provid
157b0 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 ed for by [SQLIT
157c0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
157d0 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c HE]..** ^The SQL
157e0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 ITE_CONFIG_HEAP
157f0 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 option is only a
15800 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 vailable if SQLi
15810 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a te is compiled.*
15820 2a 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 * with either [S
15830 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d QLITE_ENABLE_MEM
15840 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 SYS3] or [SQLITE
15850 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d _ENABLE_MEMSYS5]
15860 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 and returns.**
15870 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
15880 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 f invoked otherw
15890 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 ise..** ^There a
158a0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e re three argumen
158b0 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e ts to SQLITE_CON
158c0 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 FIG_HEAP:.** An
158d0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 8-byte aligned p
158e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 ointer to the me
158f0 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d mory,.** the num
15900 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
15910 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 the memory buffe
15920 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d r, and the minim
15930 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 um allocation si
15940 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 ze..** ^If the f
15950 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 irst pointer (th
15960 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 e memory pointer
15970 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 ) is NULL, then
15980 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a SQLite reverts.*
15990 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 * to using its d
159a0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c efault memory al
159b0 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 locator (the sys
159c0 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 tem malloc() imp
159d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a lementation),.**
159e0 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 undoing any pri
159f0 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 or invocation of
15a00 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
15a10 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 MALLOC]. ^If th
15a20 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e e.** memory poin
15a30 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 ter is not NULL
15a40 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 then the alterna
15a50 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 tive memory.** a
15a60 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 llocator is enga
15a70 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c ged to handle al
15a80 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d l of SQLites mem
15a90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
15aa0 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 eeds..** The fir
15ab0 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 st pointer (the
15ac0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 memory pointer)
15ad0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 must be aligned
15ae0 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 to an 8-byte.**
15af0 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 boundary or subs
15b00 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 equent behavior
15b10 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 of SQLite will b
15b20 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 e undefined..**
15b30 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f The minimum allo
15b40 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 cation size is c
15b50 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 apped at 2**12.
15b60 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 Reasonable value
15b70 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e s.** for the min
15b80 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 imum allocation
15b90 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 size are 2**5 th
15ba0 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e rough 2**8.</dd>
15bb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
15bc0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c CONFIG_MUTEX]] <
15bd0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
15be0 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c _MUTEX</dt>.** <
15bf0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 dd> ^(The SQLITE
15c00 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 _CONFIG_MUTEX op
15c10 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
15c20 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
15c30 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 ch is a.** point
15c40 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
15c50 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 e of the [sqlite
15c60 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
15c70 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 structure..** T
15c80 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 he argument spec
15c90 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 ifies alternativ
15ca0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 e low-level mute
15cb0 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 x routines to be
15cc0 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 used.** in plac
15cd0 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 e the mutex rout
15ce0 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 ines built into
15cf0 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 SQLite.)^ ^SQLi
15d00 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 te makes a copy
15d10 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e of.** the conten
15d20 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 t of the [sqlite
15d30 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
15d40 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 structure befor
15d50 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a e the call to.**
15d60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
15d70 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 ()] returns. ^If
15d80 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
15d90 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
15da0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
15db0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
15dc0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
15dd0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
15de0 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 en.** the entire
15df0 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 mutexing subsys
15e00 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 tem is omitted f
15e10 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e rom the build an
15e20 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f d hence calls to
15e30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
15e40 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 fig()] with the
15e50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
15e60 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f TEX configuratio
15e70 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a n option will.**
15e80 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
15e90 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a ERROR].</dd>.**.
15ea0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
15eb0 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 IG_GETMUTEX]] <d
15ec0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
15ed0 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a GETMUTEX</dt>.**
15ee0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 <dd> ^(The SQLI
15ef0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
15f00 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 EX option takes
15f10 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
15f20 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 t which.** is a
15f30 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
15f40 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
15f50 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
15f60 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
15f70 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 The.** [sqlite
15f80 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
15f90 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 .** structure is
15fa0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 filled with the
15fb0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e currently defin
15fc0 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 ed mutex routine
15fd0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 s.)^.** This opt
15fe0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 ion can be used
15ff0 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 to overload the
16000 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c default mutex al
16010 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 location.** rout
16020 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 ines with a wrap
16030 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 per used to trac
16040 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f k mutex usage fo
16050 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a r performance.**
16060 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 profiling or te
16070 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 sting, for examp
16080 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 le. ^If SQLite
16090 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
160a0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
160b0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
160c0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
160d0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
160e0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 option then.** t
160f0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 he entire mutexi
16100 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 ng subsystem is
16110 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 omitted from the
16120 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 build and hence
16130 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 calls to.** [sq
16140 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
16150 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f with the SQLITE_
16160 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 CONFIG_GETMUTEX
16170 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
16180 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 tion will.** ret
16190 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f urn [SQLITE_ERRO
161a0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b R].</dd>.**.** [
161b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c [SQLITE_CONFIG_L
161c0 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 OOKASIDE]] <dt>S
161d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f QLITE_CONFIG_LOO
161e0 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c KASIDE</dt>.** <
161f0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 dd> ^(The SQLITE
16200 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
16210 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 E option takes t
16220 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 wo arguments tha
16230 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 t determine.** t
16240 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 he default size
16250 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d of lookaside mem
16260 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 ory on each [dat
16270 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
16280 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 ]..** The first
16290 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a argument is the.
162a0 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 ** size of each
162b0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 lookaside buffer
162c0 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 slot and the se
162d0 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 cond is the numb
162e0 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 er of.** slots a
162f0 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 llocated to each
16300 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
16310 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 tion.)^ ^(SQLIT
16320 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
16330 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c DE.** sets the <
16340 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f i>default</i> lo
16350 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 okaside size. Th
16360 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 e [SQLITE_DBCONF
16370 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a IG_LOOKASIDE].**
16380 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 option to [sqli
16390 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d te3_db_config()]
163a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
163b0 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 change the looka
163c0 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 side.** configur
163d0 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 ation on individ
163e0 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e ual connections.
163f0 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b )^ </dd>.**.** [
16400 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
16410 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c CACHE2]] <dt>SQL
16420 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
16430 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 E2</dt>.** <dd>
16440 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^(The SQLITE_CON
16450 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 FIG_PCACHE2 opti
16460 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
16470 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
16480 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 is .** a pointe
16490 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 r to an [sqlite3
164a0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 _pcache_methods2
164b0 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 ] object. This
164c0 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 object specifies
164d0 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 .** the interfac
164e0 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 e to a custom pa
164f0 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 ge cache impleme
16500 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 ntation.)^.** ^S
16510 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f QLite makes a co
16520 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 py of the [sqlit
16530 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
16540 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e s2] object.</dd>
16550 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
16560 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
16570 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 2]] <dt>SQLITE_C
16580 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 ONFIG_GETPCACHE2
16590 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
165a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
165b0 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 G_GETPCACHE2 opt
165c0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
165d0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
165e0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 h.** is a pointe
165f0 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 r to an [sqlite3
16600 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 _pcache_methods2
16610 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 ] object. SQLit
16620 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 e copies of.** t
16630 68 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 he current page
16640 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
16650 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f tion into that o
16660 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a bject.)^ </dd>.*
16670 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
16680 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 NFIG_LOG]] <dt>S
16690 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
166a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 </dt>.** <dd> Th
166b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
166c0 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 LOG option is us
166d0 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 ed to configure
166e0 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c the SQLite.** gl
166f0 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d obal [error log]
16700 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 ..** (^The SQLIT
16710 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 E_CONFIG_LOG opt
16720 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 ion takes two ar
16730 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 guments: a point
16740 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 er to a.** funct
16750 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 ion with a call
16760 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 signature of voi
16770 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 d(*)(void*,int,c
16780 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a onst char*), .**
16790 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 and a pointer t
167a0 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 o void. ^If the
167b0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 function pointer
167c0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 is not NULL, it
167d0 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 is.** invoked b
167e0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 y [sqlite3_log()
167f0 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 ] to process eac
16800 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e h logging event.
16810 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e ^If the.** fun
16820 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 ction pointer is
16830 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 NULL, the [sqli
16840 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 te3_log()] inter
16850 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e face becomes a n
16860 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f o-op..** ^The vo
16870 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 id pointer that
16880 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 is the second ar
16890 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 gument to SQLITE
168a0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a _CONFIG_LOG is.*
168b0 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 * passed through
168c0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 as the first pa
168d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 rameter to the a
168e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
168f0 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e ed logger.** fun
16900 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 ction whenever t
16910 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 hat function is
16920 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 invoked. ^The s
16930 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
16940 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 to.** the logger
16950 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 function is a c
16960 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 opy of the first
16970 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
16980 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a e corresponding.
16990 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 ** [sqlite3_log(
169a0 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 )] call and is i
169b0 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 ntended to be a
169c0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 [result code] or
169d0 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 an.** [extended
169e0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 result code].
169f0 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d ^The third param
16a00 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 eter passed to t
16a10 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 he logger is.**
16a20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 log message afte
16a30 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 r formatting via
16a40 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e [sqlite3_snprin
16a50 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 tf()]..** The SQ
16a60 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 Lite logging int
16a70 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 erface is not re
16a80 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 entrant; the log
16a90 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ger function.**
16aa0 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 supplied by the
16ab0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
16ac0 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 not invoke any
16ad0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
16ae0 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d ..** In a multi-
16af0 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 threaded applica
16b00 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 tion, the applic
16b10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f ation-defined lo
16b20 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e gger.** function
16b30 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 must be threads
16b40 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a afe. </dd>.**.**
16b50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
16b60 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 _URI]] <dt>SQLIT
16b70 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 E_CONFIG_URI.**
16b80 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 <dd>^(The SQLITE
16b90 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 _CONFIG_URI opti
16ba0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
16bb0 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 e argument of ty
16bc0 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f pe int..** If no
16bd0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 n-zero, then URI
16be0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f handling is glo
16bf0 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 bally enabled. I
16c00 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
16c10 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e is zero,.** then
16c20 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 URI handling is
16c30 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c globally disabl
16c40 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 ed.)^ ^If URI ha
16c50 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c ndling is global
16c60 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 ly.** enabled, a
16c70 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 ll filenames pas
16c80 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f sed to [sqlite3_
16c90 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
16ca0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 3_open_v2()],.**
16cb0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
16cc0 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 ()] or.** specif
16cd0 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b ied as part of [
16ce0 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 ATTACH] commands
16cf0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 are interpreted
16d00 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 as URIs, regard
16d10 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 less.** of wheth
16d20 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 er or not the [S
16d30 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 QLITE_OPEN_URI]
16d40 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e flag is set when
16d50 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
16d60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f connection is o
16d70 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 pened. ^If it is
16d80 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c globally disabl
16d90 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 ed, filenames ar
16da0 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 e.** only interp
16db0 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 reted as URIs if
16dc0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e the SQLITE_OPEN
16dd0 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 _URI flag is set
16de0 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 when the.** dat
16df0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
16e00 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 is opened. ^(By
16e10 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 default, URI ha
16e20 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c ndling is global
16e30 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 ly.** disabled.
16e40 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 The default valu
16e50 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 e may be changed
16e60 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 by compiling wi
16e70 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 th the.** [SQLIT
16e80 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f E_USE_URI] symbo
16e90 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a l defined.)^.**.
16ea0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
16eb0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 IG_COVERING_INDE
16ec0 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c X_SCAN]] <dt>SQL
16ed0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 ITE_CONFIG_COVER
16ee0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a ING_INDEX_SCAN.*
16ef0 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 * <dd>^The SQLIT
16f00 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e E_CONFIG_COVERIN
16f10 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 G_INDEX_SCAN opt
16f20 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
16f30 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 le integer.** ar
16f40 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
16f50 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
16f60 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 boolean in orde
16f70 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 r to enable or d
16f80 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 isable.** the us
16f90 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e e of covering in
16fa0 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 dices for full t
16fb0 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 able scans in th
16fc0 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 e query optimize
16fd0 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 r..** ^The defau
16fe0 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 lt setting is de
16ff0 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 termined.** by t
17000 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 he [SQLITE_ALLOW
17010 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f _COVERING_INDEX_
17020 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 SCAN] compile-ti
17030 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 me option, or is
17040 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 "on".** if that
17050 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
17060 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e tion is omitted.
17070 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 .** The ability
17080 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 to disable the u
17090 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 se of covering i
170a0 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 ndices for full
170b0 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 table scans.** i
170c0 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 s because some i
170d0 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 ncorrectly coded
170e0 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 legacy applicat
170f0 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 ions might malfu
17100 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 nction.** when t
17110 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 he optimization
17120 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f is enabled. Pro
17130 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 viding the abili
17140 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 ty to.** disable
17150 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f the optimizatio
17160 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 n allows the old
17170 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 er, buggy applic
17180 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f ation code to wo
17190 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 rk.** without ch
171a0 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e ange even with n
171b0 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 ewer versions of
171c0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b SQLite..**.** [
171d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
171e0 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 CACHE]] [[SQLITE
171f0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 _CONFIG_GETPCACH
17200 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 E]].** <dt>SQLIT
17210 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 E_CONFIG_PCACHE
17220 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 and SQLITE_CONFI
17230 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c G_GETPCACHE.** <
17240 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e dd> These option
17250 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 s are obsolete a
17260 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 nd should not be
17270 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 used by new cod
17280 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 e..** They are r
17290 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b etained for back
172a0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
172b0 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 ity but are now
172c0 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e no-ops..** </dd>
172d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
172e0 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a CONFIG_SQLLOG]].
172f0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
17300 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c NFIG_SQLLOG.** <
17310 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 dd>This option i
17320 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 s only available
17330 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f if sqlite is co
17340 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a mpiled with the.
17350 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c ** [SQLITE_ENABL
17360 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 E_SQLLOG] pre-pr
17370 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 ocessor macro de
17380 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 fined. The first
17390 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
173a0 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 .** be a pointer
173b0 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f to a function o
173c0 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 f type void(*)(v
173d0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f oid*,sqlite3*,co
173e0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e nst char*, int).
173f0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 .** The second s
17400 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 hould be of type
17410 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 (void*). The ca
17420 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
17430 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 d by the library
17440 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 .** in three sep
17450 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e arate circumstan
17460 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 ces, identified
17470 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 by the value pas
17480 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f sed as the.** fo
17490 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 urth parameter.
174a0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
174b0 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 rameter is 0, th
174c0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
174d0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 connection.** pa
174e0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f ssed as the seco
174f0 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 nd argument has
17500 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 just been opened
17510 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 . The third argu
17520 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 ment.** points t
17530 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 o a buffer conta
17540 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f ining the name o
17550 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 f the main datab
17560 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 ase file. If the
17570 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d .** fourth param
17580 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 eter is 1, then
17590 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
175a0 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 t that the third
175b0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f parameter.** po
175c0 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 ints to has just
175d0 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 been executed.
175e0 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 Or, if the fourt
175f0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 h parameter is 2
17600 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f , then.** the co
17610 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 nnection being p
17620 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 assed as the sec
17630 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
17640 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 being closed. T
17650 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 he.** third para
17660 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 meter is passed
17670 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 NULL In this cas
17680 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f e. An example o
17690 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 f using this.**
176a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
176b0 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e tion can be seen
176c0 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 in the "test_sq
176d0 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 llog.c" source f
176e0 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 ile in.** the ca
176f0 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 nonical SQLite s
17700 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e ource tree.</dd>
17710 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
17720 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 CONFIG_MMAP_SIZE
17730 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
17740 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a _CONFIG_MMAP_SIZ
17750 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 E.** <dd>^SQLITE
17760 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a _CONFIG_MMAP_SIZ
17770 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 E takes two 64-b
17780 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 it integer (sqli
17790 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 te3_int64) value
177a0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 s.** that are th
177b0 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 e default mmap s
177c0 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 ize limit (the d
177d0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 efault setting f
177e0 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d or.** [PRAGMA mm
177f0 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 ap_size]) and th
17800 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 e maximum allowe
17810 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 d mmap size limi
17820 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 t..** ^The defau
17830 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 lt setting can b
17840 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 e overridden by
17850 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f each database co
17860 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a nnection using.*
17870 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 * either the [PR
17880 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 AGMA mmap_size]
17890 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 command, or by u
178a0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c sing the.** [SQL
178b0 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 ITE_FCNTL_MMAP_S
178c0 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f IZE] file contro
178d0 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 l. ^(The maximu
178e0 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 m allowed mmap s
178f0 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 ize.** will be s
17900 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 ilently truncate
17910 64 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 d if necessary s
17920 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e o that it does n
17930 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a ot exceed the.**
17940 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 compile-time ma
17950 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 ximum mmap size
17960 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 set by the.** [S
17970 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 QLITE_MAX_MMAP_S
17980 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d IZE] compile-tim
17990 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e e option.)^.** ^
179a0 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 If either argume
179b0 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f nt to this optio
179c0 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 n is negative, t
179d0 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e hen that argumen
179e0 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 t is.** changed
179f0 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 to its compile-t
17a00 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a ime default..**.
17a10 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
17a20 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a IG_WIN32_HEAPSIZ
17a30 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 E]].** <dt>SQLIT
17a40 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 E_CONFIG_WIN32_H
17a50 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e EAPSIZE.** <dd>^
17a60 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
17a70 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 G_WIN32_HEAPSIZE
17a80 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 option is only
17a90 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c available if SQL
17aa0 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c ite is.** compil
17ab0 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 ed for Windows w
17ac0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
17ad0 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 WIN32_MALLOC] pr
17ae0 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 e-processor macr
17af0 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 o.** defined. ^S
17b00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e QLITE_CONFIG_WIN
17b10 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 32_HEAPSIZE take
17b20 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 s a 32-bit unsig
17b30 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 ned integer valu
17b40 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 e.** that specif
17b50 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 ies the maximum
17b60 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 size of the crea
17b70 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 ted heap..**.**
17b80 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
17b90 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a PCACHE_HDRSZ]].*
17ba0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
17bb0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a FIG_PCACHE_HDRSZ
17bc0 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c .** <dd>^The SQL
17bd0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
17be0 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 E_HDRSZ option t
17bf0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 akes a single pa
17c00 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a rameter which.**
17c10 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
17c20 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 an integer and
17c30 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 writes into that
17c40 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d integer the num
17c50 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 ber of extra.**
17c60 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20 72 bytes per page r
17c70 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 equired for each
17c80 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 page in [SQLITE
17c90 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
17ca0 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e E]..** The amoun
17cb0 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 t of extra space
17cc0 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 required can ch
17cd0 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f ange depending o
17ce0 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a n the compiler,.
17cf0 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f ** target platfo
17d00 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 rm, and SQLite v
17d10 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b ersion..**.** [[
17d20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d SQLITE_CONFIG_PM
17d30 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c ASZ]].** <dt>SQL
17d40 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a ITE_CONFIG_PMASZ
17d50 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c .** <dd>^The SQL
17d60 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a ITE_CONFIG_PMASZ
17d70 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
17d80 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 single parameter
17d90 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 which.** is an
17da0 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 unsigned integer
17db0 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d and sets the "M
17dc0 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 inimum PMA Size"
17dd0 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 for the multith
17de0 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 readed.** sorter
17df0 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 to that integer
17e00 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d . The default m
17e10 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 inimum PMA Size
17e20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a is set by the.**
17e30 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f [SQLITE_SORTER_
17e40 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 PMASZ] compile-t
17e50 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 ime option. New
17e60 20 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 threads are lau
17e70 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 nched.** to help
17e80 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 with sort opera
17e90 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 tions when multi
17ea0 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 threaded sorting
17eb0 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 .** is enabled (
17ec0 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d using the [PRAGM
17ed0 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 A threads] comma
17ee0 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 nd) and the amou
17ef0 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a nt of content.**
17f00 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 to be sorted ex
17f10 63 65 65 64 73 20 74 68 65 20 70 61 67 65 20 73 ceeds the page s
17f20 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 ize times the mi
17f30 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 nimum of the.**
17f40 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 [PRAGMA cache_si
17f50 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 ze] setting and
17f60 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a this value..**.*
17f70 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
17f80 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c G_STMTJRNL_SPILL
17f90 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
17fa0 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c _CONFIG_STMTJRNL
17fb0 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 _SPILL.** <dd>^T
17fc0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
17fd0 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 _STMTJRNL_SPILL
17fe0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
17ff0 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 ingle parameter
18000 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 which.** becomes
18010 20 74 68 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 the [statement
18020 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 journal] spill-t
18030 6f 2d 64 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 o-disk threshold
18040 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e . .** [Statemen
18050 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 t journals] are
18060 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 held in memory u
18070 6e 74 69 6c 20 74 68 65 69 72 20 73 69 7a 65 20 ntil their size
18080 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 (in bytes).** ex
18090 63 65 65 64 73 20 74 68 69 73 20 74 68 72 65 73 ceeds this thres
180a0 68 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 20 70 hold, at which p
180b0 6f 69 6e 74 20 74 68 65 79 20 61 72 65 20 77 72 oint they are wr
180c0 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a itten to disk..*
180d0 2a 20 4f 72 20 69 66 20 74 68 65 20 74 68 72 65 * Or if the thre
180e0 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 shold is -1, sta
180f0 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 tement journals
18100 61 72 65 20 61 6c 77 61 79 73 20 68 65 6c 64 0a are always held.
18110 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 20 69 ** exclusively i
18120 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e n memory..** Sin
18130 63 65 20 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e ce many statemen
18140 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 t journals never
18150 20 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 become large, s
18160 65 74 74 69 6e 67 20 74 68 65 20 73 70 69 6c 6c etting the spill
18170 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 74 6f .** threshold to
18180 20 61 20 76 61 6c 75 65 20 73 75 63 68 20 61 73 a value such as
18190 20 36 34 4b 69 42 20 63 61 6e 20 67 72 65 61 74 64KiB can great
181a0 6c 79 20 72 65 64 75 63 65 20 74 68 65 20 61 6d ly reduce the am
181b0 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 ount of.** I/O r
181c0 65 71 75 69 72 65 64 20 74 6f 20 73 75 70 70 6f equired to suppo
181d0 72 74 20 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c rt statement rol
181e0 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 lback..** The de
181f0 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 fault value for
18200 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 this setting is
18210 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 controlled by th
18220 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d e.** [SQLITE_STM
18230 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d TJRNL_SPILL] com
18240 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
18250 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ..**.** [[SQLITE
18260 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 _CONFIG_SORTERRE
18270 46 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e F_SIZE]].** <dt>
18280 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f SQLITE_CONFIG_SO
18290 52 54 45 52 52 45 46 5f 53 49 5a 45 0a 2a 2a 20 RTERREF_SIZE.**
182a0 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 43 <dd>The SQLITE_C
182b0 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f ONFIG_SORTERREF_
182c0 53 49 5a 45 20 6f 70 74 69 6f 6e 20 61 63 63 65 SIZE option acce
182d0 70 74 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 pts a single par
182e0 61 6d 65 74 65 72 0a 2a 2a 20 6f 66 20 74 79 70 ameter.** of typ
182f0 65 20 28 69 6e 74 29 20 2d 20 74 68 65 20 6e 65 e (int) - the ne
18300 77 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 73 w value of the s
18310 6f 72 74 65 72 2d 72 65 66 65 72 65 6e 63 65 20 orter-reference
18320 73 69 7a 65 20 74 68 72 65 73 68 6f 6c 64 2e 0a size threshold..
18330 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e ** Usually, when
18340 20 53 51 4c 69 74 65 20 75 73 65 73 20 61 6e 20 SQLite uses an
18350 65 78 74 65 72 6e 61 6c 20 73 6f 72 74 20 74 6f external sort to
18360 20 6f 72 64 65 72 20 72 65 63 6f 72 64 73 20 61 order records a
18370 63 63 6f 72 64 69 6e 67 0a 2a 2a 20 74 6f 20 61 ccording.** to a
18380 6e 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 n ORDER BY claus
18390 65 2c 20 61 6c 6c 20 66 69 65 6c 64 73 20 72 65 e, all fields re
183a0 71 75 69 72 65 64 20 62 79 20 74 68 65 20 63 61 quired by the ca
183b0 6c 6c 65 72 20 61 72 65 20 70 72 65 73 65 6e 74 ller are present
183c0 20 69 6e 20 74 68 65 0a 2a 2a 20 73 6f 72 74 65 in the.** sorte
183d0 64 20 72 65 63 6f 72 64 73 2e 20 48 6f 77 65 76 d records. Howev
183e0 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 64 65 er, if SQLite de
183f0 74 65 72 6d 69 6e 65 73 20 62 61 73 65 64 20 6f termines based o
18400 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 n the declared t
18410 79 70 65 0a 2a 2a 20 6f 66 20 61 20 74 61 62 6c ype.** of a tabl
18420 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 74 e column that it
18430 73 20 76 61 6c 75 65 73 20 61 72 65 20 6c 69 6b s values are lik
18440 65 6c 79 20 74 6f 20 62 65 20 76 65 72 79 20 6c ely to be very l
18450 61 72 67 65 20 2d 20 6c 61 72 67 65 72 0a 2a 2a arge - larger.**
18460 20 74 68 61 6e 20 74 68 65 20 63 6f 6e 66 69 67 than the config
18470 75 72 65 64 20 73 6f 72 74 65 72 2d 72 65 66 65 ured sorter-refe
18480 72 65 6e 63 65 20 73 69 7a 65 20 74 68 72 65 73 rence size thres
18490 68 6f 6c 64 20 2d 20 74 68 65 6e 20 61 20 72 65 hold - then a re
184a0 66 65 72 65 6e 63 65 0a 2a 2a 20 69 73 20 73 74 ference.** is st
184b0 6f 72 65 64 20 69 6e 20 65 61 63 68 20 73 6f 72 ored in each sor
184c0 74 65 64 20 72 65 63 6f 72 64 20 61 6e 64 20 74 ted record and t
184d0 68 65 20 72 65 71 75 69 72 65 64 20 63 6f 6c 75 he required colu
184e0 6d 6e 20 76 61 6c 75 65 73 20 6c 6f 61 64 65 64 mn values loaded
184f0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 64 61 74 .** from the dat
18500 61 62 61 73 65 20 61 73 20 72 65 63 6f 72 64 73 abase as records
18510 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 69 6e are returned in
18520 20 73 6f 72 74 65 64 20 6f 72 64 65 72 2e 20 54 sorted order. T
18530 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 he default.** va
18540 6c 75 65 20 66 6f 72 20 74 68 69 73 20 6f 70 74 lue for this opt
18550 69 6f 6e 20 69 73 20 74 6f 20 6e 65 76 65 72 20 ion is to never
18560 75 73 65 20 74 68 69 73 20 6f 70 74 69 6d 69 7a use this optimiz
18570 61 74 69 6f 6e 2e 20 53 70 65 63 69 66 79 69 6e ation. Specifyin
18580 67 20 61 20 0a 2a 2a 20 6e 65 67 61 74 69 76 65 g a .** negative
18590 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 value for this
185a0 6f 70 74 69 6f 6e 20 72 65 73 74 6f 72 65 73 20 option restores
185b0 74 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 the default beha
185c0 76 69 6f 75 72 2e 0a 2a 2a 20 54 68 69 73 20 6f viour..** This o
185d0 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 ption is only av
185e0 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 ailable if SQLit
185f0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
18600 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 th the.** [SQLIT
18610 45 5f 45 4e 41 42 4c 45 5f 53 4f 52 54 45 52 5f E_ENABLE_SORTER_
18620 52 45 46 45 52 45 4e 43 45 53 5d 20 63 6f 6d 70 REFERENCES] comp
18630 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e ile-time option.
18640 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
18650 43 4f 4e 46 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 CONFIG_MEMDB_MAX
18660 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 SIZE]].** <dt>SQ
18670 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 44 LITE_CONFIG_MEMD
18680 42 5f 4d 41 58 53 49 5a 45 0a 2a 2a 20 3c 64 64 B_MAXSIZE.** <dd
18690 3e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 >The SQLITE_CONF
186a0 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45 IG_MEMDB_MAXSIZE
186b0 20 6f 70 74 69 6f 6e 20 61 63 63 65 70 74 73 20 option accepts
186c0 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 a single paramet
186d0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 er.** [sqlite3_i
186e0 6e 74 36 34 5d 20 70 61 72 61 6d 65 74 65 72 20 nt64] parameter
186f0 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 which is the def
18700 61 75 6c 74 20 6d 61 78 69 6d 75 6d 20 73 69 7a ault maximum siz
18710 65 20 66 6f 72 20 61 6e 20 69 6e 2d 6d 65 6d 6f e for an in-memo
18720 72 79 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ry.** database c
18730 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 reated using [sq
18740 6c 69 74 65 33 5f 64 65 73 65 72 69 61 6c 69 7a lite3_deserializ
18750 65 28 29 5d 2e 20 20 54 68 69 73 20 64 65 66 61 e()]. This defa
18760 75 6c 74 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 73 ult maximum.** s
18770 69 7a 65 20 63 61 6e 20 62 65 20 61 64 6a 75 73 ize can be adjus
18780 74 65 64 20 75 70 20 6f 72 20 64 6f 77 6e 20 66 ted up or down f
18790 6f 72 20 69 6e 64 69 76 69 64 75 61 6c 20 64 61 or individual da
187a0 74 61 62 61 73 65 73 20 75 73 69 6e 67 20 74 68 tabases using th
187b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e e.** [SQLITE_FCN
187c0 54 4c 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 5b TL_SIZE_LIMIT] [
187d0 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
187e0 74 72 6f 6c 7c 66 69 6c 65 2d 63 6f 6e 74 72 6f trol|file-contro
187f0 6c 5d 2e 20 20 49 66 20 74 68 69 73 0a 2a 2a 20 l]. If this.**
18800 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 65 configuration se
18810 74 74 69 6e 67 20 69 73 20 6e 65 76 65 72 20 75 tting is never u
18820 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 65 sed, then the de
18830 66 61 75 6c 74 20 6d 61 78 69 6d 75 6d 20 69 73 fault maximum is
18840 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 determined.** b
18850 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 45 y the [SQLITE_ME
18860 4d 44 42 5f 44 45 46 41 55 4c 54 5f 4d 41 58 53 MDB_DEFAULT_MAXS
18870 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d IZE] compile-tim
18880 65 20 6f 70 74 69 6f 6e 2e 20 20 49 66 20 74 68 e option. If th
18890 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 at.** compile-ti
188a0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 74 me option is not
188b0 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 set, then the d
188c0 65 66 61 75 6c 74 20 6d 61 78 69 6d 75 6d 20 69 efault maximum i
188d0 73 20 31 30 37 33 37 34 31 38 32 34 2e 0a 2a 2a s 1073741824..**
188e0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </dl>.*/.#defin
188f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
18900 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 SINGLETHREAD 1
18910 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
18920 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18930 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 _MULTITHREAD 2
18940 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
18950 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
18960 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 G_SERIALIZED
18970 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 3 /* nil */.#de
18980 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
18990 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 IG_MALLOC
189a0 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 4 /* sqlite3_m
189b0 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 em_methods* */.#
189c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
189d0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 NFIG_GETMALLOC
189e0 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5 /* sqlite3
189f0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f _mem_methods* */
18a00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18a10 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 CONFIG_SCRATCH
18a20 20 20 20 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6 /* No lo
18a30 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 nger used */.#de
18a40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
18a50 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 IG_PAGECACHE
18a60 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 7 /* void*, in
18a70 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 t sz, int N */.#
18a80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
18a90 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 NFIG_HEAP
18aa0 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 8 /* void*,
18ab0 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d int nByte, int m
18ac0 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 in */.#define SQ
18ad0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
18ae0 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 TATUS 9 /*
18af0 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 boolean */.#defi
18b00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18b10 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 _MUTEX 10
18b20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 /* sqlite3_mut
18b30 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 ex_methods* */.#
18b40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
18b50 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 NFIG_GETMUTEX
18b60 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 11 /* sqlite3
18b70 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 _mutex_methods*
18b80 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 */./* previously
18b90 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 SQLITE_CONFIG_C
18ba0 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 HUNKALLOC 12 whi
18bb0 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 ch is now unused
18bc0 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 . */ .#define SQ
18bd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
18be0 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 ASIDE 13 /*
18bf0 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 int int */.#defi
18c00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18c10 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 _PCACHE 14
18c20 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 /* no-op */.#d
18c30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
18c40 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 FIG_GETPCACHE
18c50 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 15 /* no-op */
18c60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18c70 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 CONFIG_LOG
18c80 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 16 /* xFunc
18c90 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 , void* */.#defi
18ca0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18cb0 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 _URI 17
18cc0 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 /* int */.#def
18cd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
18ce0 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 G_PCACHE2 1
18cf0 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 8 /* sqlite3_pc
18d00 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a ache_methods2* *
18d10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18d20 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 _CONFIG_GETPCACH
18d30 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 E2 19 /* sqli
18d40 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
18d50 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ds2* */.#define
18d60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f SQLITE_CONFIG_CO
18d70 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 VERING_INDEX_SCA
18d80 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a N 20 /* int */.
18d90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
18da0 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 ONFIG_SQLLOG
18db0 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 21 /* xSqllo
18dc0 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 g, void* */.#def
18dd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
18de0 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 G_MMAP_SIZE 2
18df0 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 2 /* sqlite3_in
18e00 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 t64, sqlite3_int
18e10 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 64 */.#define SQ
18e20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 LITE_CONFIG_WIN3
18e30 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 2_HEAPSIZE
18e40 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 23 /* int nByte
18e50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18e60 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
18e70 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 _HDRSZ 24
18e80 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f /* int *psz */
18e90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18ea0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 CONFIG_PMASZ
18eb0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 25 /
18ec0 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 * unsigned int s
18ed0 7a 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 zPma */.#define
18ee0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 SQLITE_CONFIG_ST
18ef0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 MTJRNL_SPILL
18f00 20 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 26 /* int nBy
18f10 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 te */.#define SQ
18f20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c LITE_CONFIG_SMAL
18f30 4c 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 L_MALLOC
18f40 32 37 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 27 /* boolean *
18f50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18f60 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 _CONFIG_SORTERRE
18f70 46 5f 53 49 5a 45 20 20 20 20 20 20 32 38 20 20 F_SIZE 28
18f80 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a /* int nByte */.
18f90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
18fa0 4f 4e 46 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 ONFIG_MEMDB_MAXS
18fb0 49 5a 45 20 20 20 20 20 20 20 32 39 20 20 2f 2a IZE 29 /*
18fc0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
18fd0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
18fe0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e F: Database Conn
18ff0 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 ection Configura
19000 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a tion Options.**.
19010 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
19020 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c ts are the avail
19030 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e able integer con
19040 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
19050 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 ns that.** can b
19060 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
19070 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
19080 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
19090 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 db_config()] int
190a0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 erface..**.** Ne
190b0 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 w configuration
190c0 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 options may be a
190d0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
190e0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
190f0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 e..** Existing c
19100 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
19110 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 ions might be di
19120 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 scontinued. App
19130 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f lications.** sho
19140 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 uld check the re
19150 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b turn code from [
19160 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
19170 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 g()] to make sur
19180 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 e that.** the ca
19190 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 ll worked. ^The
191a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
191b0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
191c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a will return a.*
191d0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f * non-zero [erro
191e0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 r code] if a dis
191f0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 continued or uns
19200 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 upported configu
19210 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a ration option.**
19220 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a is invoked..**.
19230 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c ** <dl>.** [[SQL
19240 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
19250 4b 41 53 49 44 45 5d 5d 0a 2a 2a 20 3c 64 74 3e KASIDE]].** <dt>
19260 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
19270 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a LOOKASIDE</dt>.*
19280 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
19290 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 ion takes three
192a0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d additional argum
192b0 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d ents that determ
192c0 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f ine the .** [loo
192d0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c kaside memory al
192e0 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 locator] configu
192f0 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b ration for the [
19300 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
19310 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 ion]..** ^The fi
19320 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 rst argument (th
19330 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
19340 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 r to [sqlite3_db
19350 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a _config()] is a.
19360 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 ** pointer to a
19370 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f memory buffer to
19380 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 use for lookasi
19390 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 de memory..** ^T
193a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
193b0 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 t after the SQLI
193c0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
193d0 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 ASIDE verb.** ma
193e0 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 y be NULL in whi
193f0 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 ch case SQLite w
19400 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 ill allocate the
19410 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 .** lookaside bu
19420 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e ffer itself usin
19430 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f g [sqlite3_mallo
19440 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e c()]. ^The secon
19450 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
19460 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 e.** size of eac
19470 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 h lookaside buff
19480 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 er slot. ^The t
19490 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
194a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
194b0 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 * slots. The si
194c0 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 ze of the buffer
194d0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
194e0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 gument must be g
194f0 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f reater than.** o
19500 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 r equal to the p
19510 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 roduct of the se
19520 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 cond and third a
19530 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 rguments. The b
19540 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 uffer.** must be
19550 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 aligned to an 8
19560 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 -byte boundary.
19570 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 ^If the second
19580 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 argument to.** S
19590 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
195a0 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 OOKASIDE is not
195b0 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c a multiple of 8,
195c0 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c it is internall
195d0 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 y.** rounded dow
195e0 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d n to the next sm
195f0 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f aller multiple o
19600 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b f 8. ^(The look
19610 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 aside memory.**
19620 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f configuration fo
19630 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e r a database con
19640 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 nection can only
19650 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e be changed when
19660 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 that.** connect
19670 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 ion is not curre
19680 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 ntly using looka
19690 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 side memory, or
196a0 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a in other words.*
196b0 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 * when the "curr
196c0 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 ent value" retur
196d0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ned by.** [sqlit
196e0 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c e3_db_status](D,
196f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c [SQLITE_CONFIG_L
19700 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 OOKASIDE],...) i
19710 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 s zero..** Any a
19720 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 ttempt to change
19730 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d the lookaside m
19740 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 emory configurat
19750 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 ion when lookasi
19760 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 de.** memory is
19770 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 in use leaves th
19780 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 e configuration
19790 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 unchanged and re
197a0 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 turns .** [SQLIT
197b0 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a E_BUSY].)^</dd>.
197c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 **.** [[SQLITE_D
197d0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 BCONFIG_ENABLE_F
197e0 4b 45 59 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c KEY]].** <dt>SQL
197f0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
19800 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a BLE_FKEY</dt>.**
19810 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
19820 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e on is used to en
19830 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 able or disable
19840 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 the enforcement
19850 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b of.** [foreign k
19860 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e ey constraints].
19870 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 There should b
19880 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c e two additional
19890 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 arguments..** T
198a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
198b0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 t is an integer
198c0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 which is 0 to di
198d0 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 sable FK enforce
198e0 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 ment,.** positiv
198f0 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 e to enable FK e
19900 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 nforcement or ne
19910 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 gative to leave
19920 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a FK enforcement.*
19930 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 * unchanged. Th
19940 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
19950 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 er is a pointer
19960 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e to an integer in
19970 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 to which.** is w
19980 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f ritten 0 or 1 to
19990 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 indicate whethe
199a0 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 r FK enforcement
199b0 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a is off or on.**
199c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 following this
199d0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e call. The secon
199e0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 d parameter may
199f0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 be a NULL pointe
19a00 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 r, in.** which c
19a10 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 ase the FK enfor
19a20 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 cement setting i
19a30 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 s not reported b
19a40 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ack. </dd>.**.**
19a50 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 [[SQLITE_DBCONF
19a60 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 IG_ENABLE_TRIGGE
19a70 52 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 R]].** <dt>SQLIT
19a80 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
19a90 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a E_TRIGGER</dt>.*
19aa0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
19ab0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 ion is used to e
19ac0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 nable or disable
19ad0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 [CREATE TRIGGER
19ae0 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a | triggers]..**
19af0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 There should be
19b00 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 two additional
19b10 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 arguments..** Th
19b20 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
19b30 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 is an integer w
19b40 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 hich is 0 to dis
19b50 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a able triggers,.*
19b60 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e * positive to en
19b70 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 able triggers or
19b80 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 negative to lea
19b90 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 ve the setting u
19ba0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 nchanged..** The
19bb0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
19bc0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 r is a pointer t
19bd0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 o an integer int
19be0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 o which.** is wr
19bf0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 itten 0 or 1 to
19c00 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 indicate whether
19c10 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 triggers are di
19c20 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 sabled or enable
19c30 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 d.** following t
19c40 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 his call. The s
19c50 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
19c60 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f may be a NULL po
19c70 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 inter, in.** whi
19c80 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 ch case the trig
19c90 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e ger setting is n
19ca0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b ot reported back
19cb0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b . </dd>.**.** [[
19cc0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
19cd0 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 ENABLE_FTS3_TOKE
19ce0 4e 49 5a 45 52 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 NIZER]].** <dt>S
19cf0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
19d00 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e NABLE_FTS3_TOKEN
19d10 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 IZER</dt>.** <dd
19d20 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 > ^This option i
19d30 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 s used to enable
19d40 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 0a or disable the.
19d50 2a 2a 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a ** [fts3_tokeniz
19d60 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 er()] function w
19d70 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 hich is part of
19d80 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 the.** [FTS3] fu
19d90 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 ll-text search e
19da0 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e ngine extension.
19db0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 .** There should
19dc0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e be two addition
19dd0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a al arguments..**
19de0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
19df0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ent is an intege
19e00 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 r which is 0 to
19e10 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b disable fts3_tok
19e20 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 enizer() or.** p
19e30 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c ositive to enabl
19e40 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 e fts3_tokenizer
19e50 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 () or negative t
19e60 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 o leave the sett
19e70 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 ing.** unchanged
19e80 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
19e90 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
19ea0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
19eb0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a eger into which.
19ec0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 ** is written 0
19ed0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 or 1 to indicate
19ee0 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f whether fts3_to
19ef0 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 kenizer is disab
19f00 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a led or enabled.*
19f10 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 * following this
19f20 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f call. The seco
19f30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 nd parameter may
19f40 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 be a NULL point
19f50 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 er, in.** which
19f60 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 case the new set
19f70 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f ting is not repo
19f80 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e rted back. </dd>
19f90 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
19fa0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
19fb0 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 5d 5d LOAD_EXTENSION]]
19fc0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
19fd0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c BCONFIG_ENABLE_L
19fe0 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 OAD_EXTENSION</d
19ff0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
1a000 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 option is used
1a010 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 to enable or dis
1a020 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 able the [sqlite
1a030 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 3_load_extension
1a040 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
1a050 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f independently o
1a060 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 f the [load_exte
1a070 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e nsion()] SQL fun
1a080 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 ction..** The [s
1a090 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f qlite3_enable_lo
1a0a0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 ad_extension()]
1a0b0 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 API enables or d
1a0c0 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68 65 isables both the
1a0d0 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69 74 .** C-API [sqlit
1a0e0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f e3_load_extensio
1a0f0 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51 4c n()] and the SQL
1a100 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f function [load_
1a110 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a extension()]..**
1a120 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 There should be
1a130 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 two additional
1a140 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 arguments..** Wh
1a150 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 en the first arg
1a160 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69 6e ument to this in
1a170 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 74 68 terface is 1, th
1a180 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50 en only the C-AP
1a190 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 I is.** enabled
1a1a0 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 and the SQL func
1a1b0 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69 73 tion remains dis
1a1c0 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20 66 abled. If the f
1a1d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
1a1e0 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61 .** this interfa
1a1f0 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62 6f ce is 0, then bo
1a200 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e 64 th the C-API and
1a210 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
1a220 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e 0a n are disabled..
1a230 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 74 20 ** If the first
1a240 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20 argument is -1,
1a250 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20 then no changes
1a260 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61 74 are made to stat
1a270 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 65 0a e of either the.
1a280 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65 20 ** C-API or the
1a290 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a SQL function..**
1a2a0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
1a2b0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 meter is a point
1a2c0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 er to an integer
1a2d0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 into which.** i
1a2e0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 s written 0 or 1
1a2f0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 to indicate whe
1a300 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f ther [sqlite3_lo
1a310 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 ad_extension()]
1a320 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 interface.** is
1a330 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 disabled or enab
1a340 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 led following th
1a350 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 is call. The se
1a360 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d cond parameter m
1a370 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20 ay.** be a NULL
1a380 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69 63 pointer, in whic
1a390 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 h case the new s
1a3a0 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 etting is not re
1a3b0 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 ported back..**
1a3c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
1a3d0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 LITE_DBCONFIG_MA
1a3e0 49 4e 44 42 4e 41 4d 45 5d 5d 20 3c 64 74 3e 53 INDBNAME]] <dt>S
1a3f0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d QLITE_DBCONFIG_M
1a400 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a AINDBNAME</dt>.*
1a410 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
1a420 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 ion is used to c
1a430 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65 20 6f hange the name o
1a440 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64 61 74 f the "main" dat
1a450 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e abase.** schema.
1a460 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72 67 75 ^The sole argu
1a470 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
1a480 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20 r to a constant
1a490 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77 UTF8 string.** w
1a4a0 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65 hich will become
1a4b0 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d 61 20 the new schema
1a4c0 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 name in place of
1a4d0 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74 "main". ^SQLit
1a4e0 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61 e.** does not ma
1a4f0 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 ke a copy of the
1a500 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65 6d 61 new main schema
1a510 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f name string, so
1a520 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
1a530 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 .** must ensure
1a540 74 68 61 74 20 74 68 65 20 61 72 67 75 6d 65 6e that the argumen
1a550 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 t passed into th
1a560 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70 74 69 is DBCONFIG opti
1a570 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65 64 0a on is unchanged.
1a580 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 ** until after t
1a590 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1a5a0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a ection closes..*
1a5b0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b * </dd>.**.** [[
1a5c0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
1a5d0 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 NO_CKPT_ON_CLOSE
1a5e0 5d 5d 20 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 ]] .** <dt>SQLIT
1a5f0 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b E_DBCONFIG_NO_CK
1a600 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e PT_ON_CLOSE</dt>
1a610 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 .** <dd> Usually
1a620 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 , when a databas
1a630 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 e in wal mode is
1a640 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74 61 63 closed or detac
1a650 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 hed from a .** d
1a660 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 atabase handle,
1a670 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20 69 66 SQLite checks if
1a680 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 this will mean
1a690 74 68 61 74 20 74 68 65 72 65 20 61 72 65 20 6e that there are n
1a6a0 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 ow no .** connec
1a6b0 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 tions at all to
1a6c0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 49 66 the database. If
1a6d0 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 so, it performs
1a6e0 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a a checkpoint .*
1a6f0 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65 66 6f * operation befo
1a700 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 re closing the c
1a710 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 onnection. This
1a720 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 option may be us
1a730 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 ed to.** overrid
1a740 65 20 74 68 69 73 20 62 65 68 61 76 69 6f 75 72 e this behaviour
1a750 2e 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 . The first para
1a760 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 meter passed to
1a770 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a this operation.*
1a780 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 * is an integer
1a790 2d 20 70 6f 73 69 74 69 76 65 20 74 6f 20 64 69 - positive to di
1a7a0 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 sable checkpoint
1a7b0 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a s-on-close, or z
1a7c0 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 ero (the.** defa
1a7d0 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 ult) to enable t
1a7e0 68 65 6d 2c 20 61 6e 64 20 6e 65 67 61 74 69 76 hem, and negativ
1a7f0 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 e to leave the s
1a800 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 etting unchanged
1a810 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
1a820 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
1a830 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
1a840 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 eger.** into whi
1a850 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 ch is written 0
1a860 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 or 1 to indicate
1a870 20 77 68 65 74 68 65 72 20 63 68 65 63 6b 70 6f whether checkpo
1a880 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a ints-on-close.**
1a890 20 68 61 76 65 20 62 65 65 6e 20 64 69 73 61 62 have been disab
1a8a0 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65 79 20 led - 0 if they
1a8b0 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 are not disabled
1a8c0 2c 20 31 20 69 66 20 74 68 65 79 20 61 72 65 2e , 1 if they are.
1a8d0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .** </dd>.**.**
1a8e0 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 [[SQLITE_DBCONFI
1a8f0 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 5d 5d 20 G_ENABLE_QPSG]]
1a900 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e <dt>SQLITE_DBCON
1a910 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c FIG_ENABLE_QPSG<
1a920 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 /dt>.** <dd>^(Th
1a930 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
1a940 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 G_ENABLE_QPSG op
1a950 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f tion activates o
1a960 72 20 64 65 61 63 74 69 76 61 74 65 73 0a 2a 2a r deactivates.**
1a970 20 74 68 65 20 5b 71 75 65 72 79 20 70 6c 61 6e the [query plan
1a980 6e 65 72 20 73 74 61 62 69 6c 69 74 79 20 67 75 ner stability gu
1a990 61 72 61 6e 74 65 65 5d 20 28 51 50 53 47 29 2e arantee] (QPSG).
1a9a0 20 20 57 68 65 6e 20 74 68 65 20 51 50 53 47 20 When the QPSG
1a9b0 69 73 20 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 is active,.** a
1a9c0 73 69 6e 67 6c 65 20 53 51 4c 20 71 75 65 72 79 single SQL query
1a9d0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 statement will
1a9e0 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20 73 always use the s
1a9f0 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 ame algorithm re
1aa00 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 gardless.** of v
1aa10 61 6c 75 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 alues of [bound
1aa20 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 parameters].)^ T
1aa30 68 65 20 51 50 53 47 20 64 69 73 61 62 6c 65 73 he QPSG disables
1aa40 20 73 6f 6d 65 20 71 75 65 72 79 20 6f 70 74 69 some query opti
1aa50 6d 69 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 mizations.** tha
1aa60 74 20 6c 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 t look at the va
1aa70 6c 75 65 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 lues of bound pa
1aa80 72 61 6d 65 74 65 72 73 2c 20 77 68 69 63 68 20 rameters, which
1aa90 63 61 6e 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 can make some qu
1aaa0 65 72 69 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e eries.** slower.
1aab0 20 20 42 75 74 20 74 68 65 20 51 50 53 47 20 68 But the QPSG h
1aac0 61 73 20 74 68 65 20 61 64 76 61 6e 74 61 67 65 as the advantage
1aad0 20 6f 66 20 6d 6f 72 65 20 70 72 65 64 69 63 74 of more predict
1aae0 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 20 20 able behavior.
1aaf0 57 69 74 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 With.** the QPSG
1ab00 20 61 63 74 69 76 65 2c 20 53 51 4c 69 74 65 20 active, SQLite
1ab10 77 69 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20 will always use
1ab20 74 68 65 20 73 61 6d 65 20 71 75 65 72 79 20 70 the same query p
1ab30 6c 61 6e 20 69 6e 20 74 68 65 20 66 69 65 6c 64 lan in the field
1ab40 20 61 73 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 as.** was used
1ab50 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 69 during testing i
1ab60 6e 20 74 68 65 20 6c 61 62 2e 0a 2a 2a 20 54 68 n the lab..** Th
1ab70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
1ab80 20 74 6f 20 74 68 69 73 20 73 65 74 74 69 6e 67 to this setting
1ab90 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 is an integer w
1aba0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 hich is 0 to dis
1abb0 61 62 6c 65 20 0a 2a 2a 20 74 68 65 20 51 50 53 able .** the QPS
1abc0 47 2c 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 G, positive to e
1abd0 6e 61 62 6c 65 20 51 50 53 47 2c 20 6f 72 20 6e nable QPSG, or n
1abe0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 egative to leave
1abf0 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 the setting.**
1ac00 75 6e 63 68 61 6e 67 65 64 2e 20 54 68 65 20 73 unchanged. The s
1ac10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1ac20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
1ac30 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 an integer into
1ac40 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 which.** is writ
1ac50 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e ten 0 or 1 to in
1ac60 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 dicate whether t
1ac70 68 65 20 51 50 53 47 20 69 73 20 64 69 73 61 62 he QPSG is disab
1ac80 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a led or enabled.*
1ac90 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 * following this
1aca0 20 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a call..** </dd>.
1acb0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 **.** [[SQLITE_D
1acc0 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f BCONFIG_TRIGGER_
1acd0 45 51 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 EQP]] <dt>SQLITE
1ace0 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 _DBCONFIG_TRIGGE
1acf0 52 5f 45 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 R_EQP</dt>.** <d
1ad00 64 3e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 d> By default, t
1ad10 68 65 20 6f 75 74 70 75 74 20 6f 66 20 45 58 50 he output of EXP
1ad20 4c 41 49 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 LAIN QUERY PLAN
1ad30 63 6f 6d 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f commands does no
1ad40 74 20 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75 t .** include ou
1ad50 74 70 75 74 20 66 6f 72 20 61 6e 79 20 6f 70 65 tput for any ope
1ad60 72 61 74 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 rations performe
1ad70 64 20 62 79 20 74 72 69 67 67 65 72 20 70 72 6f d by trigger pro
1ad80 67 72 61 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f grams. This.** o
1ad90 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f ption is used to
1ada0 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 28 74 set or clear (t
1adb0 68 65 20 64 65 66 61 75 6c 74 29 20 61 20 66 6c he default) a fl
1adc0 61 67 20 74 68 61 74 20 67 6f 76 65 72 6e 73 20 ag that governs
1add0 74 68 69 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72 this.** behavior
1ade0 2e 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 . The first para
1adf0 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 meter passed to
1ae00 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 20 69 this operation i
1ae10 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a s an integer -.*
1ae20 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e * positive to en
1ae30 61 62 6c 65 20 6f 75 74 70 75 74 20 66 6f 72 20 able output for
1ae40 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 trigger programs
1ae50 2c 20 6f 72 20 7a 65 72 6f 20 74 6f 20 64 69 73 , or zero to dis
1ae60 61 62 6c 65 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e able it,.** or n
1ae70 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 egative to leave
1ae80 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 the setting unc
1ae90 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 hanged..** The s
1aea0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1aeb0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
1aec0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 an integer into
1aed0 77 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e which is written
1aee0 20 0a 2a 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 .** 0 or 1 to i
1aef0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 ndicate whether
1af00 6f 75 74 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 output-for-trigg
1af10 65 72 73 20 68 61 73 20 62 65 65 6e 20 64 69 73 ers has been dis
1af20 61 62 6c 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a abled - 0 if .**
1af30 20 69 74 20 69 73 20 6e 6f 74 20 64 69 73 61 62 it is not disab
1af40 6c 65 64 2c 20 31 20 69 66 20 69 74 20 69 73 2e led, 1 if it is.
1af50 20 20 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a .** </dd>.**.*
1af60 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e * [[SQLITE_DBCON
1af70 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41 FIG_RESET_DATABA
1af80 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f SE]] <dt>SQLITE_
1af90 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 DBCONFIG_RESET_D
1afa0 41 54 41 42 41 53 45 3c 2f 64 74 3e 0a 2a 2a 20 ATABASE</dt>.**
1afb0 3c 64 64 3e 20 53 65 74 20 74 68 65 20 53 51 4c <dd> Set the SQL
1afc0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 ITE_DBCONFIG_RES
1afd0 45 54 5f 44 41 54 41 42 41 53 45 20 66 6c 61 67 ET_DATABASE flag
1afe0 20 61 6e 64 20 74 68 65 6e 20 72 75 6e 0a 2a 2a and then run.**
1aff0 20 5b 56 41 43 55 55 4d 5d 20 69 6e 20 6f 72 64 [VACUUM] in ord
1b000 65 72 20 74 6f 20 72 65 73 65 74 20 61 20 64 61 er to reset a da
1b010 74 61 62 61 73 65 20 62 61 63 6b 20 74 6f 20 61 tabase back to a
1b020 6e 20 65 6d 70 74 79 20 64 61 74 61 62 61 73 65 n empty database
1b030 0a 2a 2a 20 77 69 74 68 20 6e 6f 20 73 63 68 65 .** with no sche
1b040 6d 61 20 61 6e 64 20 6e 6f 20 63 6f 6e 74 65 6e ma and no conten
1b050 74 2e 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 t. The following
1b060 20 70 72 6f 63 65 73 73 20 77 6f 72 6b 73 20 65 process works e
1b070 76 65 6e 20 66 6f 72 0a 2a 2a 20 61 20 62 61 64 ven for.** a bad
1b080 6c 79 20 63 6f 72 72 75 70 74 65 64 20 64 61 74 ly corrupted dat
1b090 61 62 61 73 65 20 66 69 6c 65 3a 0a 2a 2a 20 3c abase file:.** <
1b0a0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 74 ol>.** <li> If t
1b0b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1b0c0 65 63 74 69 6f 6e 20 69 73 20 6e 65 77 6c 79 20 ection is newly
1b0d0 6f 70 65 6e 65 64 2c 20 6d 61 6b 65 20 73 75 72 opened, make sur
1b0e0 65 20 69 74 20 68 61 73 20 72 65 61 64 20 74 68 e it has read th
1b0f0 65 0a 2a 2a 20 20 20 20 20 20 64 61 74 61 62 61 e.** databa
1b100 73 65 20 73 63 68 65 6d 61 20 62 79 20 70 72 65 se schema by pre
1b110 70 61 72 69 6e 67 20 74 68 65 6e 20 64 69 73 63 paring then disc
1b120 61 72 64 69 6e 67 20 73 6f 6d 65 20 71 75 65 72 arding some quer
1b130 79 20 61 67 61 69 6e 73 74 20 74 68 65 0a 2a 2a y against the.**
1b140 20 20 20 20 20 20 64 61 74 61 62 61 73 65 2c 20 database,
1b150 6f 72 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 or calling sqlit
1b160 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f e3_table_column_
1b170 6d 65 74 61 64 61 74 61 28 29 2c 20 69 67 6e 6f metadata(), igno
1b180 72 69 6e 67 20 61 6e 79 0a 2a 2a 20 20 20 20 20 ring any.**
1b190 20 65 72 72 6f 72 73 2e 20 20 54 68 69 73 20 73 errors. This s
1b1a0 74 65 70 20 69 73 20 6f 6e 6c 79 20 6e 65 63 65 tep is only nece
1b1b0 73 73 61 72 79 20 69 66 20 74 68 65 20 61 70 70 ssary if the app
1b1c0 6c 69 63 61 74 69 6f 6e 20 64 65 73 69 72 65 73 lication desires
1b1d0 20 74 6f 20 6b 65 65 70 0a 2a 2a 20 20 20 20 20 to keep.**
1b1e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e the database in
1b1f0 20 57 41 4c 20 6d 6f 64 65 20 61 66 74 65 72 20 WAL mode after
1b200 74 68 65 20 72 65 73 65 74 20 69 66 20 69 74 20 the reset if it
1b210 77 61 73 20 69 6e 20 57 41 4c 20 6d 6f 64 65 20 was in WAL mode
1b220 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 74 before.** t
1b230 68 65 20 72 65 73 65 74 2e 20 20 0a 2a 2a 20 3c he reset. .** <
1b240 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 li> sqlite3_db_c
1b250 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c 49 54 45 onfig(db, SQLITE
1b260 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f _DBCONFIG_RESET_
1b270 44 41 54 41 42 41 53 45 2c 20 31 2c 20 30 29 3b DATABASE, 1, 0);
1b280 0a 2a 2a 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 .** <li> [sqlite
1b290 33 5f 65 78 65 63 5d 28 64 62 2c 20 22 5b 56 41 3_exec](db, "[VA
1b2a0 43 55 55 4d 5d 22 2c 20 30 2c 20 30 2c 20 30 29 CUUM]", 0, 0, 0)
1b2b0 3b 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 ;.** <li> sqlite
1b2c0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64 62 2c 20 3_db_config(db,
1b2d0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
1b2e0 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 2c 20 RESET_DATABASE,
1b2f0 30 2c 20 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 0, 0);.** </ol>.
1b300 2a 2a 20 42 65 63 61 75 73 65 20 72 65 73 65 74 ** Because reset
1b310 74 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 ting a database
1b320 69 73 20 64 65 73 74 72 75 63 74 69 76 65 20 61 is destructive a
1b330 6e 64 20 69 72 72 65 76 65 72 73 69 62 6c 65 2c nd irreversible,
1b340 20 74 68 65 0a 2a 2a 20 70 72 6f 63 65 73 73 20 the.** process
1b350 72 65 71 75 69 72 65 73 20 74 68 65 20 75 73 65 requires the use
1b360 20 6f 66 20 74 68 69 73 20 6f 62 73 63 75 72 65 of this obscure
1b370 20 41 50 49 20 61 6e 64 20 6d 75 6c 74 69 70 6c API and multipl
1b380 65 20 73 74 65 70 73 20 74 6f 20 68 65 6c 70 0a e steps to help.
1b390 2a 2a 20 65 6e 73 75 72 65 20 74 68 61 74 20 69 ** ensure that i
1b3a0 74 20 64 6f 65 73 20 6e 6f 74 20 68 61 70 70 65 t does not happe
1b3b0 6e 20 62 79 20 61 63 63 69 64 65 6e 74 2e 0a 2a n by accident..*
1b3c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 *.** [[SQLITE_DB
1b3d0 43 4f 4e 46 49 47 5f 44 45 46 45 4e 53 49 56 45 CONFIG_DEFENSIVE
1b3e0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 ]] <dt>SQLITE_DB
1b3f0 43 4f 4e 46 49 47 5f 44 45 46 45 4e 53 49 56 45 CONFIG_DEFENSIVE
1b400 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1b410 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
1b420 5f 44 45 46 45 4e 53 49 56 45 20 6f 70 74 69 6f _DEFENSIVE optio
1b430 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 n activates or d
1b440 65 61 63 74 69 76 61 74 65 73 20 74 68 65 0a 2a eactivates the.*
1b450 2a 20 22 64 65 66 65 6e 73 69 76 65 22 20 66 6c * "defensive" fl
1b460 61 67 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 ag for a databas
1b470 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 57 e connection. W
1b480 68 65 6e 20 74 68 65 20 64 65 66 65 6e 73 69 76 hen the defensiv
1b490 65 0a 2a 2a 20 66 6c 61 67 20 69 73 20 65 6e 61 e.** flag is ena
1b4a0 62 6c 65 64 2c 20 6c 61 6e 67 75 61 67 65 20 66 bled, language f
1b4b0 65 61 74 75 72 65 73 20 74 68 61 74 20 61 6c 6c eatures that all
1b4c0 6f 77 20 6f 72 64 69 6e 61 72 79 20 53 51 4c 20 ow ordinary SQL
1b4d0 74 6f 20 0a 2a 2a 20 64 65 6c 69 62 65 72 61 74 to .** deliberat
1b4e0 65 6c 79 20 63 6f 72 72 75 70 74 20 74 68 65 20 ely corrupt the
1b4f0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 72 database file ar
1b500 65 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 e disabled. The
1b510 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 65 61 disabled.** fea
1b520 74 75 72 65 73 20 69 6e 63 6c 75 64 65 20 62 75 tures include bu
1b530 74 20 61 72 65 20 6e 6f 74 20 6c 69 6d 69 74 65 t are not limite
1b540 64 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 d to the followi
1b550 6e 67 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c ng:.** <ul>.** <
1b560 6c 69 3e 20 54 68 65 20 5b 50 52 41 47 4d 41 20 li> The [PRAGMA
1b570 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61 3d writable_schema=
1b580 4f 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a ON] statement..*
1b590 2a 20 3c 6c 69 3e 20 57 72 69 74 65 73 20 74 6f * <li> Writes to
1b5a0 20 74 68 65 20 5b 73 71 6c 69 74 65 5f 64 62 70 the [sqlite_dbp
1b5b0 61 67 65 5d 20 76 69 72 74 75 61 6c 20 74 61 62 age] virtual tab
1b5c0 6c 65 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 69 72 65 le..** <li> Dire
1b5d0 63 74 20 77 72 69 74 65 73 20 74 6f 20 5b 73 68 ct writes to [sh
1b5e0 61 64 6f 77 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a adow tables]..**
1b5f0 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a </ul>.** </dd>.
1b600 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 **.** [[SQLITE_D
1b610 42 43 4f 4e 46 49 47 5f 57 52 49 54 41 42 4c 45 BCONFIG_WRITABLE
1b620 5f 53 43 48 45 4d 41 5d 5d 20 3c 64 74 3e 53 51 _SCHEMA]] <dt>SQ
1b630 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 57 52 LITE_DBCONFIG_WR
1b640 49 54 41 42 4c 45 5f 53 43 48 45 4d 41 3c 2f 64 ITABLE_SCHEMA</d
1b650 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 t>.** <dd>The SQ
1b660 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 57 52 LITE_DBCONFIG_WR
1b670 49 54 41 42 4c 45 5f 53 43 48 45 4d 41 20 6f 70 ITABLE_SCHEMA op
1b680 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f tion activates o
1b690 72 20 64 65 61 63 74 69 76 61 74 65 73 20 74 68 r deactivates th
1b6a0 65 0a 2a 2a 20 22 77 72 69 74 61 62 6c 65 5f 73 e.** "writable_s
1b6b0 63 68 65 6d 61 22 20 66 6c 61 67 2e 20 54 68 69 chema" flag. Thi
1b6c0 73 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65 s has the same e
1b6d0 66 66 65 63 74 20 61 6e 64 20 69 73 20 6c 6f 67 ffect and is log
1b6e0 69 63 61 6c 6c 79 20 65 71 75 69 76 61 6c 65 6e ically equivalen
1b6f0 74 0a 2a 2a 20 74 6f 20 73 65 74 74 69 6e 67 20 t.** to setting
1b700 5b 50 52 41 47 4d 41 20 77 72 69 74 61 62 6c 65 [PRAGMA writable
1b710 5f 73 63 68 65 6d 61 3d 4f 4e 5d 20 6f 72 20 5b _schema=ON] or [
1b720 50 52 41 47 4d 41 20 77 72 69 74 61 62 6c 65 5f PRAGMA writable_
1b730 73 63 68 65 6d 61 3d 4f 46 46 5d 2e 0a 2a 2a 20 schema=OFF]..**
1b740 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
1b750 6e 74 20 74 6f 20 74 68 69 73 20 73 65 74 74 69 nt to this setti
1b760 6e 67 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ng is an integer
1b770 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 which is 0 to d
1b780 69 73 61 62 6c 65 20 0a 2a 2a 20 74 68 65 20 77 isable .** the w
1b790 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61 2c 20 ritable_schema,
1b7a0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 positive to enab
1b7b0 6c 65 20 77 72 69 74 61 62 6c 65 5f 73 63 68 65 le writable_sche
1b7c0 6d 61 2c 20 6f 72 20 6e 65 67 61 74 69 76 65 20 ma, or negative
1b7d0 74 6f 0a 2a 2a 20 6c 65 61 76 65 20 74 68 65 20 to.** leave the
1b7e0 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 setting unchange
1b7f0 64 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 d. The second pa
1b800 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 rameter is a poi
1b810 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
1b820 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 teger into which
1b830 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 is written 0 or
1b840 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 1 to indicate w
1b850 68 65 74 68 65 72 20 74 68 65 20 77 72 69 74 61 hether the writa
1b860 62 6c 65 5f 73 63 68 65 6d 61 0a 2a 2a 20 69 73 ble_schema.** is
1b870 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 enabled or disa
1b880 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 bled following t
1b890 68 69 73 20 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 his call..** </d
1b8a0 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 d>.** </dl>.*/.#
1b8b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
1b8c0 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d CONFIG_MAINDBNAM
1b8d0 45 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30 E 100
1b8e0 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68 61 72 2a 0 /* const char*
1b8f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1b900 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
1b910 41 53 49 44 45 20 20 20 20 20 20 20 20 20 20 20 ASIDE
1b920 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 1001 /* void*
1b930 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 int int */.#defi
1b940 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
1b950 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 IG_ENABLE_FKEY
1b960 20 20 20 20 20 20 20 20 20 31 30 30 32 20 2f 2a 1002 /*
1b970 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 int int* */.#de
1b980 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
1b990 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 NFIG_ENABLE_TRIG
1b9a0 47 45 52 20 20 20 20 20 20 20 20 31 30 30 33 20 GER 1003
1b9b0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 /* int int* */.#
1b9c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
1b9d0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 CONFIG_ENABLE_FT
1b9e0 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30 S3_TOKENIZER 100
1b9f0 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 4 /* int int* */
1ba00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1ba10 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
1ba20 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31 LOAD_EXTENSION 1
1ba30 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 005 /* int int*
1ba40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1ba50 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b E_DBCONFIG_NO_CK
1ba60 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20 20 20 PT_ON_CLOSE
1ba70 20 31 30 30 36 20 2f 2a 20 69 6e 74 20 69 6e 74 1006 /* int int
1ba80 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
1ba90 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
1baa0 42 4c 45 5f 51 50 53 47 20 20 20 20 20 20 20 20 BLE_QPSG
1bab0 20 20 20 31 30 30 37 20 2f 2a 20 69 6e 74 20 69 1007 /* int i
1bac0 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nt* */.#define S
1bad0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 54 QLITE_DBCONFIG_T
1bae0 52 49 47 47 45 52 5f 45 51 50 20 20 20 20 20 20 RIGGER_EQP
1baf0 20 20 20 20 20 31 30 30 38 20 2f 2a 20 69 6e 74 1008 /* int
1bb00 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 int* */.#define
1bb10 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
1bb20 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 20 _RESET_DATABASE
1bb30 20 20 20 20 20 20 20 31 30 30 39 20 2f 2a 20 69 1009 /* i
1bb40 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 nt int* */.#defi
1bb50 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
1bb60 49 47 5f 44 45 46 45 4e 53 49 56 45 20 20 20 20 IG_DEFENSIVE
1bb70 20 20 20 20 20 20 20 20 20 31 30 31 30 20 2f 2a 1010 /*
1bb80 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 int int* */.#de
1bb90 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
1bba0 4e 46 49 47 5f 57 52 49 54 41 42 4c 45 5f 53 43 NFIG_WRITABLE_SC
1bbb0 48 45 4d 41 20 20 20 20 20 20 20 31 30 31 31 20 HEMA 1011
1bbc0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 /* int int* */.#
1bbd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
1bbe0 43 4f 4e 46 49 47 5f 4d 41 58 20 20 20 20 20 20 CONFIG_MAX
1bbf0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30 31 101
1bc00 31 20 2f 2a 20 4c 61 72 67 65 73 74 20 44 42 43 1 /* Largest DBC
1bc10 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 ONFIG */../*.**
1bc20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 CAPI3REF: Enable
1bc30 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 Or Disable Exte
1bc40 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 nded Result Code
1bc50 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
1bc60 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ite3.**.** ^The
1bc70 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
1bc80 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 _result_codes()
1bc90 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 routine enables
1bca0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a or disables the.
1bcb0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
1bcc0 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 ult codes] featu
1bcd0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 re of SQLite. ^T
1bce0 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 he extended resu
1bcf0 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 lt.** codes are
1bd00 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
1bd10 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 ult for historic
1bd20 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 al compatibility
1bd30 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
1bd40 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
1bd50 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c _codes(sqlite3*,
1bd60 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a int onoff);../*
1bd70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 .** CAPI3REF: La
1bd80 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a st Insert Rowid.
1bd90 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
1bda0 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 e3.**.** ^Each e
1bdb0 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c ntry in most SQL
1bdc0 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 ite tables (exce
1bdd0 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 pt for [WITHOUT
1bde0 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a ROWID] tables).*
1bdf0 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 * has a unique 6
1be00 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 4-bit signed.**
1be10 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c integer key call
1be20 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 ed the [ROWID |
1be30 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 "rowid"]. ^The r
1be40 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 owid is always a
1be50 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 vailable.** as a
1be60 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c n undeclared col
1be70 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c umn named ROWID,
1be80 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f OID, or _ROWID_
1be90 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 as long as thos
1bea0 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e e.** names are n
1beb0 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 ot also used by
1bec0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 explicitly decla
1bed0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 red columns. ^If
1bee0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 .** the table ha
1bef0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 s a column of ty
1bf00 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d pe [INTEGER PRIM
1bf10 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 ARY KEY] then th
1bf20 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 at column.** is
1bf30 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f another alias fo
1bf40 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a r the rowid..**.
1bf50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1bf60 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
1bf70 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 75 d(D) interface u
1bf80 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 sually returns t
1bf90 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a he [rowid] of.**
1bfa0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
1bfb0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 successful [INS
1bfc0 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 ERT] into a rowi
1bfd0 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 d table or [virt
1bfe0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e ual table].** on
1bff0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1c000 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73 tion D. ^Inserts
1c010 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 into [WITHOUT R
1c020 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 OWID] tables are
1c030 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64 not.** recorded
1c040 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 . ^If no success
1c050 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e ful [INSERT]s in
1c060 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 to rowid tables
1c070 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 have ever occurr
1c080 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61 ed .** on the da
1c090 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1c0a0 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 n D, then sqlite
1c0b0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
1c0c0 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 0a wid(D) returns .
1c0d0 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 ** zero..**.** A
1c0e0 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e 67 20 s well as being
1c0f0 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c set automaticall
1c100 79 20 61 73 20 72 6f 77 73 20 61 72 65 20 69 6e y as rows are in
1c110 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61 74 61 serted into data
1c120 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 base.** tables,
1c130 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
1c140 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 ed by this funct
1c150 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20 65 ion may be set e
1c160 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20 xplicitly by.**
1c170 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 [sqlite3_set_las
1c180 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 t_insert_rowid()
1c190 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 ].**.** Some vir
1c1a0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 tual table imple
1c1b0 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 49 mentations may I
1c1c0 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74 6f 20 NSERT rows into
1c1d0 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61 73 0a rowid tables as.
1c1e0 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69 ** part of commi
1c1f0 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 tting a transact
1c200 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75 ion (e.g. to flu
1c210 73 68 20 64 61 74 61 20 61 63 63 75 6d 75 6c 61 sh data accumula
1c220 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a ted in memory.**
1c230 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74 68 to disk). In th
1c240 69 73 20 63 61 73 65 20 73 75 62 73 65 71 75 65 is case subseque
1c250 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68 69 73 nt calls to this
1c260 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
1c270 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73 the rowid.** as
1c280 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
1c290 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53 ese internal INS
1c2a0 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 ERT operations,
1c2b0 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f 20 0a which leads to .
1c2c0 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65 20 72 ** unintuitive r
1c2d0 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61 6c 20 esults. Virtual
1c2e0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 table implementa
1c2f0 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20 77 72 tions that do wr
1c300 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 ite to rowid.**
1c310 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73 20 77 tables in this w
1c320 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74 68 69 ay can avoid thi
1c330 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72 65 73 s problem by res
1c340 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 toring the origi
1c350 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61 nal .** rowid va
1c360 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 lue using [sqlit
1c370 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 e3_set_last_inse
1c380 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65 66 6f rt_rowid()] befo
1c390 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a re returning .**
1c3a0 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20 control to the
1c3b0 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 user..**.** ^(If
1c3c0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 an [INSERT] occ
1c3d0 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 urs within a tri
1c3e0 67 67 65 72 20 74 68 65 6e 20 74 68 69 73 20 72 gger then this r
1c3f0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 outine will .**
1c400 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 return the [rowi
1c410 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 d] of the insert
1c420 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 ed row as long a
1c430 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73 s the trigger is
1c440 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e .** running. On
1c450 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 70 ce the trigger p
1c460 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74 68 65 rogram ends, the
1c470 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
1c480 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 .** by this rout
1c490 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 ine reverts to w
1c4a0 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 hat it was befor
1c4b0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 77 61 e the trigger wa
1c4c0 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a s fired.)^.**.**
1c4d0 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 ^An [INSERT] th
1c4e0 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 at fails due to
1c4f0 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f a constraint vio
1c500 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a lation is not a.
1c510 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 ** successful [I
1c520 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 NSERT] and does
1c530 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 not change the v
1c540 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
1c550 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 this.** routine
1c560 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 . ^Thus INSERT
1c570 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 OR FAIL, INSERT
1c580 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 OR IGNORE, INSER
1c590 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a T OR ROLLBACK,.*
1c5a0 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 * and INSERT OR
1c5b0 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 ABORT make no ch
1c5c0 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 anges to the ret
1c5d0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 urn value of thi
1c5e0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 s.** routine whe
1c5f0 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f n their insertio
1c600 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e n fails. ^(When
1c610 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 INSERT OR REPLA
1c620 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 CE.** encounters
1c630 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 a constraint vi
1c640 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 olation, it does
1c650 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a not fail. The.
1c660 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e ** INSERT contin
1c670 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f ues to completio
1c680 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 n after deleting
1c690 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 rows that cause
1c6a0 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 d.** the constra
1c6b0 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 int problem so I
1c6c0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 NSERT OR REPLACE
1c6d0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 will always cha
1c6e0 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 nge.** the retur
1c6f0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 n value of this
1c700 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a interface.)^.**.
1c710 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 ** ^For the purp
1c720 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 oses of this rou
1c730 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 tine, an [INSERT
1c740 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 ] is considered
1c750 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 to.** be success
1c760 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 ful even if it i
1c770 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 s subsequently r
1c780 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a olled back..**.*
1c790 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
1c7a0 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f is accessible to
1c7b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
1c7c0 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 via the.** [last
1c7d0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 _insert_rowid()
1c7e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a SQL function]..*
1c7f0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 *.** If a separa
1c800 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 te thread perfor
1c810 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 ms a new [INSERT
1c820 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a ] on the same.**
1c830 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1c840 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b tion while the [
1c850 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
1c860 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 ert_rowid()].**
1c870 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
1c880 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 ing and thus cha
1c890 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e nges the last in
1c8a0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a sert [rowid],.**
1c8b0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 then the value
1c8c0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
1c8d0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
1c8e0 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 _rowid()] is.**
1c8f0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
1c900 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 d might not equa
1c910 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 l either the old
1c920 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c or the new.** l
1c930 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 ast insert [rowi
1c940 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 d]..*/.sqlite3_i
1c950 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 nt64 sqlite3_las
1c960 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 t_insert_rowid(s
1c970 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
1c980 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 74 CAPI3REF: Set t
1c990 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 he Last Insert R
1c9a0 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d owid value..** M
1c9b0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
1c9c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
1c9d0 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 _set_last_insert
1c9e0 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74 _rowid(D, R) met
1c9f0 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 hod allows the a
1ca00 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a pplication to.**
1ca10 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 72 set the value r
1ca20 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 eturned by calli
1ca30 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f ng sqlite3_last_
1ca40 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 insert_rowid(D)
1ca50 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 to R .** without
1ca60 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77 inserting a row
1ca70 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 into the databa
1ca80 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 se..*/.void sqli
1ca90 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 te3_set_last_ins
1caa0 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 ert_rowid(sqlite
1cab0 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3*,sqlite3_int64
1cac0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1cad0 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 EF: Count The Nu
1cae0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 mber Of Rows Mod
1caf0 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a ified.** METHOD:
1cb00 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
1cb10 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
1cb20 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
1cb30 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 of rows modifie
1cb40 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a d, inserted or.*
1cb50 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 * deleted by the
1cb60 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 most recently c
1cb70 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c ompleted INSERT,
1cb80 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 UPDATE or DELET
1cb90 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f E.** statement o
1cba0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
1cbb0 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 onnection specif
1cbc0 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 ied by the only
1cbd0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 parameter..** ^E
1cbe0 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 xecuting any oth
1cbf0 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 er type of SQL s
1cc00 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f tatement does no
1cc10 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c t modify the val
1cc20 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 ue.** returned b
1cc30 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e y this function.
1cc40 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 .**.** ^Only cha
1cc50 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 nges made direct
1cc60 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 ly by the INSERT
1cc70 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 , UPDATE or DELE
1cc80 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 TE statement are
1cc90 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d .** considered -
1cca0 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 auxiliary chang
1ccb0 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 es caused by [CR
1ccc0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 EATE TRIGGER | t
1ccd0 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 riggers], .** [f
1cce0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f oreign key actio
1ccf0 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d ns] or [REPLACE]
1cd00 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f constraint reso
1cd10 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 lution are not c
1cd20 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 ounted..** .** C
1cd30 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 hanges to a view
1cd40 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 that are interc
1cd50 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e epted by .** [IN
1cd60 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 STEAD OF trigger
1cd70 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 | INSTEAD OF tr
1cd80 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 iggers] are not
1cd90 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 counted. ^The va
1cda0 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 lue .** returned
1cdb0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e by sqlite3_chan
1cdc0 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c ges() immediatel
1cdd0 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 y after an INSER
1cde0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a T, UPDATE or .**
1cdf0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e DELETE statemen
1ce00 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 t run on a view
1ce10 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 is always zero.
1ce20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 Only changes mad
1ce30 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 e to real .** ta
1ce40 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 bles are counted
1ce50 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 ..**.** Things a
1ce60 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 re more complica
1ce70 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 ted if the sqlit
1ce80 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e e3_changes() fun
1ce90 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 ction is.** exec
1cea0 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 uted while a tri
1ceb0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 gger program is
1cec0 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 running. This ma
1ced0 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a y happen if the.
1cee0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 ** program uses
1cef0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 the [changes() S
1cf00 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 QL function], or
1cf10 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 if some other c
1cf20 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 allback.** funct
1cf30 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 ion invokes sqli
1cf40 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 te3_changes() di
1cf50 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 rectly. Essentia
1cf60 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e lly:.** .** <ul>
1cf70 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 .** <li> ^(Bef
1cf80 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 ore entering a t
1cf90 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 rigger program t
1cfa0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
1cfb0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 d by.** s
1cfc0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
1cfd0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 function is sav
1cfe0 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 ed. After the tr
1cff0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a igger program .*
1d000 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e * has fin
1d010 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 ished, the origi
1d020 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 nal value is res
1d030 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 tored.)^.** .**
1d040 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 <li> ^(Within
1d050 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 a trigger progra
1d060 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 m each INSERT, U
1d070 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 PDATE and DELETE
1d080 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 .** stat
1d090 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 ement sets the v
1d0a0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
1d0b0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
1d0c0 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 () .** up
1d0d0 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 on completion as
1d0e0 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 normal. Of cour
1d0f0 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 se, this value w
1d100 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 ill not include
1d110 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 .** any c
1d120 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 hanges performed
1d130 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 by sub-triggers
1d140 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 , as the sqlite3
1d150 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 _changes() .**
1d160 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c value will
1d170 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 be saved and re
1d180 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 stored after eac
1d190 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 h sub-trigger ha
1d1a0 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c s run.)^.** </ul
1d1b0 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d >.** .** ^This m
1d1c0 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 eans that if the
1d1d0 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 changes() SQL f
1d1e0 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 unction (or simi
1d1f0 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 lar) is used.**
1d200 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 by the first INS
1d210 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 ERT, UPDATE or D
1d220 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 ELETE statement
1d230 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 within a trigger
1d240 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 , it .** returns
1d250 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 the value as se
1d260 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 t when the calli
1d270 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 ng statement beg
1d280 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a an executing..**
1d290 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20 ^If it is used
1d2a0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 by the second or
1d2b0 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 subsequent such
1d2c0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 statement withi
1d2d0 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 n a trigger .**
1d2e0 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c program, the val
1d2f0 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c ue returned refl
1d300 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 ects the number
1d310 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 of rows modified
1d320 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 by the .** prev
1d330 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 ious INSERT, UPD
1d340 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 ATE or DELETE st
1d350 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 atement within t
1d360 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e he same trigger.
1d370 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 .**.** If a sepa
1d380 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 rate thread make
1d390 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 s changes on the
1d3a0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
1d3b0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 onnection.** whi
1d3c0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e le [sqlite3_chan
1d3d0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e ges()] is runnin
1d3e0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 g then the value
1d3f0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 returned.** is
1d400 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
1d410 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c d not meaningful
1d420 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
1d430 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 :.** <ul>.** <li
1d440 3e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 > the [sqlite3_t
1d450 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 otal_changes()]
1d460 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 3c 6c 69 interface.** <li
1d470 3e 20 74 68 65 20 5b 63 6f 75 6e 74 5f 63 68 61 > the [count_cha
1d480 6e 67 65 73 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 nges pragma].**
1d490 3c 6c 69 3e 20 74 68 65 20 5b 63 68 61 6e 67 65 <li> the [change
1d4a0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e s() SQL function
1d4b0 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 64 ].** <li> the [d
1d4c0 61 74 61 5f 76 65 72 73 69 6f 6e 20 70 72 61 67 ata_version prag
1d4d0 6d 61 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a ma].** </ul>.*/.
1d4e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e int sqlite3_chan
1d4f0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a ges(sqlite3*);..
1d500 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1d510 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 Total Number Of
1d520 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a Rows Modified.**
1d530 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
1d540 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e .**.** ^This fun
1d550 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
1d560 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f e total number o
1d570 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c f rows inserted,
1d580 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 modified or.**
1d590 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b deleted by all [
1d5a0 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 INSERT], [UPDATE
1d5b0 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 ] or [DELETE] st
1d5c0 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 atements complet
1d5d0 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 ed.** since the
1d5e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1d5f0 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 ion was opened,
1d600 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 including those
1d610 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 executed as.** p
1d620 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 art of trigger p
1d630 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 rograms. ^Execut
1d640 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 ing any other ty
1d650 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d pe of SQL statem
1d660 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 ent.** does not
1d670 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 affect the value
1d680 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
1d690 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
1d6a0 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 es()..** .** ^Ch
1d6b0 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 anges made as pa
1d6c0 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b rt of [foreign k
1d6d0 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 ey actions] are
1d6e0 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a included in the.
1d6f0 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 ** count, but th
1d700 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 ose made as part
1d710 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 of REPLACE cons
1d720 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f traint resolutio
1d730 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 n are.** not. ^C
1d740 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 hanges to a view
1d750 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 that are interc
1d760 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 epted by INSTEAD
1d770 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a OF triggers .**
1d780 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 are not counted
1d790 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c ..**.** The [sql
1d7a0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
1d7b0 65 73 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 es(D)] interface
1d7c0 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 74 68 only reports th
1d7d0 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 72 e number.** of r
1d7e0 6f 77 73 20 74 68 61 74 20 63 68 61 6e 67 65 64 ows that changed
1d7f0 20 64 75 65 20 74 6f 20 53 51 4c 20 73 74 61 74 due to SQL stat
1d800 65 6d 65 6e 74 20 72 75 6e 20 61 67 61 69 6e 73 ement run agains
1d810 74 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f t database.** co
1d820 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 79 nnection D. Any
1d830 20 63 68 61 6e 67 65 73 20 62 79 20 6f 74 68 65 changes by othe
1d840 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 r database conne
1d850 63 74 69 6f 6e 73 20 61 72 65 20 69 67 6e 6f 72 ctions are ignor
1d860 65 64 2e 0a 2a 2a 20 54 6f 20 64 65 74 65 63 74 ed..** To detect
1d870 20 63 68 61 6e 67 65 73 20 61 67 61 69 6e 73 74 changes against
1d880 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
1d890 20 66 72 6f 6d 20 6f 74 68 65 72 20 64 61 74 61 from other data
1d8a0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
1d8b0 6f 6e 73 20 75 73 65 20 74 68 65 20 5b 50 52 41 ons use the [PRA
1d8c0 47 4d 41 20 64 61 74 61 5f 76 65 72 73 69 6f 6e GMA data_version
1d8d0 5d 20 63 6f 6d 6d 61 6e 64 20 6f 72 20 74 68 65 ] command or the
1d8e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 .** [SQLITE_FCNT
1d8f0 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20 L_DATA_VERSION]
1d900 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 5d 2e 0a [file control]..
1d910 2a 2a 20 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 ** .** If a sepa
1d920 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 rate thread make
1d930 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 s changes on the
1d940 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
1d950 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 onnection.** whi
1d960 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 le [sqlite3_tota
1d970 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 l_changes()] is
1d980 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 running then the
1d990 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e value.** return
1d9a0 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 ed is unpredicta
1d9b0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e ble and not mean
1d9c0 69 6e 67 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 ingful..**.** Se
1d9d0 65 20 61 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e 0a e also:.** <ul>.
1d9e0 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 73 71 6c ** <li> the [sql
1d9f0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 ite3_changes()]
1da00 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 3c 6c 69 interface.** <li
1da10 3e 20 74 68 65 20 5b 63 6f 75 6e 74 5f 63 68 61 > the [count_cha
1da20 6e 67 65 73 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 nges pragma].**
1da30 3c 6c 69 3e 20 74 68 65 20 5b 63 68 61 6e 67 65 <li> the [change
1da40 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e s() SQL function
1da50 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 64 ].** <li> the [d
1da60 61 74 61 5f 76 65 72 73 69 6f 6e 20 70 72 61 67 ata_version prag
1da70 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 ma].** <li> the
1da80 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 [SQLITE_FCNTL_DA
1da90 54 41 5f 56 45 52 53 49 4f 4e 5d 20 5b 66 69 6c TA_VERSION] [fil
1daa0 65 20 63 6f 6e 74 72 6f 6c 5d 0a 2a 2a 20 3c 2f e control].** </
1dab0 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ul>.*/.int sqlit
1dac0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
1dad0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
1dae0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 ** CAPI3REF: Int
1daf0 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 errupt A Long-Ru
1db00 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d nning Query.** M
1db10 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
1db20 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 *.** ^This funct
1db30 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 ion causes any p
1db40 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 ending database
1db50 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f operation to abo
1db60 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e rt and.** return
1db70 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 at its earliest
1db80 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 opportunity. Th
1db90 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 is routine is ty
1dba0 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 pically.** calle
1dbb0 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f d in response to
1dbc0 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 a user action s
1dbd0 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 uch as pressing
1dbe0 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 "Cancel".** or C
1dbf0 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 trl-C where the
1dc00 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e user wants a lon
1dc10 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f g query operatio
1dc20 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d n to halt.** imm
1dc30 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ediately..**.**
1dc40 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 ^It is safe to c
1dc50 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 all this routine
1dc60 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 from a thread d
1dc70 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 ifferent from th
1dc80 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 e.** thread that
1dc90 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 is currently ru
1dca0 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 nning the databa
1dcb0 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 se operation. B
1dcc0 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 ut it.** is not
1dcd0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 safe to call thi
1dce0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 s routine with a
1dcf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1dd00 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 ction] that.** i
1dd10 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 s closed or migh
1dd20 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 t close before s
1dd30 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1dd40 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a () returns..**.*
1dd50 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 * ^If an SQL ope
1dd60 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e ration is very n
1dd70 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 early finished a
1dd80 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a t the time when.
1dd90 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 ** sqlite3_inter
1dda0 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 rupt() is called
1ddb0 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 , then it might
1ddc0 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f not have an oppo
1ddd0 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 rtunity.** to be
1dde0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 interrupted and
1ddf0 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 might continue
1de00 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a to completion..*
1de10 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 *.** ^An SQL ope
1de20 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 ration that is i
1de30 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 nterrupted will
1de40 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 return [SQLITE_I
1de50 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 NTERRUPT]..** ^I
1de60 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 f the interrupte
1de70 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 d SQL operation
1de80 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 is an INSERT, UP
1de90 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a DATE, or DELETE.
1dea0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 ** that is insid
1deb0 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 e an explicit tr
1dec0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 ansaction, then
1ded0 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 the entire trans
1dee0 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 action.** will b
1def0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 e rolled back au
1df00 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a tomatically..**.
1df10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1df20 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c interrupt(D) cal
1df30 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 l is in effect u
1df40 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 ntil all current
1df50 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 ly running.** SQ
1df60 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 L statements on
1df70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1df80 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 tion] D complete
1df90 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 . ^Any new SQL
1dfa0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 statements.** th
1dfb0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 at are started a
1dfc0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 fter the sqlite3
1dfd0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c _interrupt() cal
1dfe0 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 l and before the
1dff0 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 .** running sta
1e000 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 tements reaches
1e010 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 zero are interru
1e020 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 pted as if they
1e030 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e had been.** runn
1e040 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 ing prior to the
1e050 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
1e060 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 pt() call. ^New
1e070 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
1e080 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 ** that are star
1e090 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 ted after the ru
1e0a0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 nning statement
1e0b0 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 count reaches ze
1e0c0 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 ro are.** not ef
1e0d0 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 fected by the sq
1e0e0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
1e0f0 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f )..** ^A call to
1e100 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
1e110 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 pt(D) that occur
1e120 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 s when there are
1e130 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 no running.** S
1e140 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 QL statements is
1e150 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 a no-op and has
1e160 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 no effect on SQ
1e170 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
1e180 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 that are started
1e190 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 after the sqlit
1e1a0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 e3_interrupt() c
1e1b0 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a all returns..*/.
1e1c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 void sqlite3_int
1e1d0 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 errupt(sqlite3*)
1e1e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1e1f0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
1e200 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
1e210 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a Is Complete.**.
1e220 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
1e230 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 s are useful dur
1e240 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 ing command-line
1e250 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d input to determ
1e260 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 ine if the.** cu
1e270 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 rrently entered
1e280 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f text seems to fo
1e290 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 rm a complete SQ
1e2a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a L statement or.*
1e2b0 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 * if additional
1e2c0 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 input is needed
1e2d0 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 before sending t
1e2e0 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 he text into.**
1e2f0 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 SQLite for parsi
1e300 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 ng. ^These rout
1e310 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 ines return 1 if
1e320 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e the input strin
1e330 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 g.** appears to
1e340 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 be a complete SQ
1e350 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 L statement. ^A
1e360 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 statement is ju
1e370 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f dged to be.** co
1e380 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 mplete if it end
1e390 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c s with a semicol
1e3a0 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 on token and is
1e3b0 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 not a prefix of
1e3c0 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 a.** well-formed
1e3d0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 CREATE TRIGGER
1e3e0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d statement. ^Sem
1e3f0 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 icolons that are
1e400 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e embedded within
1e410 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 .** string liter
1e420 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 als or quoted id
1e430 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f entifier names o
1e440 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e r comments are n
1e450 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e ot.** independen
1e460 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 t tokens (they a
1e470 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 re part of the t
1e480 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 oken in which th
1e490 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 ey are.** embedd
1e4a0 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 ed) and thus do
1e4b0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 not count as a s
1e4c0 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 tatement termina
1e4d0 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 tor. ^Whitespac
1e4e0 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 e.** and comment
1e4f0 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 s that follow th
1e500 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f e final semicolo
1e510 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a n are ignored..*
1e520 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
1e530 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 ines return 0 if
1e540 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
1e550 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e s incomplete. ^
1e560 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 If a.** memory a
1e570 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c llocation fails,
1e580 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d then SQLITE_NOM
1e590 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a EM is returned..
1e5a0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
1e5b0 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 tines do not par
1e5c0 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 se the SQL state
1e5d0 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 ments thus.** wi
1e5e0 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 ll not detect sy
1e5f0 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f ntactically inco
1e600 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a rrect SQL..**.**
1e610 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 ^(If SQLite has
1e620 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 not been initia
1e630 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c lized using [sql
1e640 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
1e650 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 )] prior .** to
1e660 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 invoking sqlite3
1e670 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 _complete16() th
1e680 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 en sqlite3_initi
1e690 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
1e6a0 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 ed.** automatica
1e6b0 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 lly by sqlite3_c
1e6c0 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 omplete16(). If
1e6d0 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 that initializa
1e6e0 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 tion fails,.** t
1e6f0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 hen the return v
1e700 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
1e710 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 3_complete16() w
1e720 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a ill be non-zero.
1e730 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ** regardless of
1e740 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
1e750 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 the input SQL is
1e760 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a complete.)^.**.
1e770 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 ** The input to
1e780 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
1e790 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a e()] must be a z
1e7a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
1e7b0 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a * UTF-8 string..
1e7c0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 **.** The input
1e7d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 to [sqlite3_comp
1e7e0 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 lete16()] must b
1e7f0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 e a zero-termina
1e800 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 ted.** UTF-16 st
1e810 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 ring in native b
1e820 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e yte order..*/.in
1e830 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 t sqlite3_comple
1e840 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 te(const char *s
1e850 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ql);.int sqlite3
1e860 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 _complete16(cons
1e870 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f t void *sql);../
1e880 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
1e890 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 egister A Callba
1e8a0 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c ck To Handle SQL
1e8b0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a ITE_BUSY Errors.
1e8c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 ** KEYWORDS: {bu
1e8d0 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 sy-handler callb
1e8e0 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c ack} {busy handl
1e8f0 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 er}.** METHOD: s
1e900 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
1e910 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 e sqlite3_busy_h
1e920 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f andler(D,X,P) ro
1e930 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c utine sets a cal
1e940 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 lback function X
1e950 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 .** that might b
1e960 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 e invoked with a
1e970 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 rgument P whenev
1e980 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 er.** an attempt
1e990 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 is made to acce
1e9a0 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 ss a database ta
1e9b0 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 ble associated w
1e9c0 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 ith.** [database
1e9d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 connection] D w
1e9e0 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 hen another thre
1e9f0 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 ad.** or process
1ea00 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c has the table l
1ea10 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 ocked..** The sq
1ea20 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
1ea30 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 er() interface i
1ea40 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d s used to implem
1ea50 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ent.** [sqlite3_
1ea60 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 busy_timeout()]
1ea70 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 and [PRAGMA busy
1ea80 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a _timeout]..**.**
1ea90 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 ^If the busy ca
1eaa0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 llback is NULL,
1eab0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 then [SQLITE_BUS
1eac0 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 Y].** is returne
1ead0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 d immediately up
1eae0 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 on encountering
1eaf0 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 the lock. ^If t
1eb00 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
1eb10 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c .** is not NULL,
1eb20 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 then the callba
1eb30 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f ck might be invo
1eb40 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 ked with two arg
1eb50 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 uments..**.** ^T
1eb60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
1eb70 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 t to the busy ha
1eb80 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 ndler is a copy
1eb90 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 of the void* poi
1eba0 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 nter which.** is
1ebb0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d the third argum
1ebc0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ent to sqlite3_b
1ebd0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 usy_handler().
1ebe0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 ^The second argu
1ebf0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 ment to.** the b
1ec00 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c usy handler call
1ec10 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 back is the numb
1ec20 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 er of times that
1ec30 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
1ec40 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e r has.** been in
1ec50 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 voked previously
1ec60 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f for the same lo
1ec70 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 cking event. ^I
1ec80 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 f the.** busy ca
1ec90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 llback returns 0
1eca0 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 , then no additi
1ecb0 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 onal attempts ar
1ecc0 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 e made to.** acc
1ecd0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ess the database
1ece0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 and [SQLITE_BUS
1ecf0 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a Y] is returned.*
1ed00 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 * to the applica
1ed10 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 tion..** ^If the
1ed20 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
1ed30 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e s non-zero, then
1ed40 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 another attempt
1ed50 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 .** is made to a
1ed60 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 ccess the databa
1ed70 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 se and the cycle
1ed80 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 repeats..**.**
1ed90 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 The presence of
1eda0 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 a busy handler d
1edb0 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 oes not guarante
1edc0 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 e that it will b
1edd0 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 e invoked.** whe
1ede0 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 n there is lock
1edf0 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 contention. ^If
1ee00 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 SQLite determine
1ee10 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 s that invoking
1ee20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 the busy.** hand
1ee30 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 ler could result
1ee40 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 in a deadlock,
1ee50 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 it will go ahead
1ee60 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c and return [SQL
1ee70 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 ITE_BUSY].** to
1ee80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
1ee90 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b instead of invok
1eea0 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 ing the .** busy
1eeb0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e handler..** Con
1eec0 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f sider a scenario
1eed0 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 where one proce
1eee0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 ss is holding a
1eef0 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a read lock that.*
1ef00 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 * it is trying t
1ef10 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 o promote to a r
1ef20 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 eserved lock and
1ef30 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f .** a second pro
1ef40 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 cess is holding
1ef50 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 a reserved lock
1ef60 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e that it is tryin
1ef70 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 g.** to promote
1ef80 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 to an exclusive
1ef90 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 lock. The first
1efa0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 process cannot
1efb0 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 proceed.** becau
1efc0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 se it is blocked
1efd0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 by the second a
1efe0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 nd the second pr
1eff0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 ocess cannot.**
1f000 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 proceed because
1f010 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 it is blocked by
1f020 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 the first. If
1f030 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a both processes.*
1f040 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 * invoke the bus
1f050 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 y handlers, neit
1f060 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e her will make an
1f070 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 y progress. The
1f080 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 refore,.** SQLit
1f090 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 e returns [SQLIT
1f0a0 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 E_BUSY] for the
1f0b0 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 first process, h
1f0c0 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a oping that this.
1f0d0 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 ** will induce t
1f0e0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 he first process
1f0f0 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 to release its
1f100 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c read lock and al
1f110 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e low.** the secon
1f120 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f d process to pro
1f130 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ceed..**.** ^The
1f140 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 default busy ca
1f150 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a llback is NULL..
1f160 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 **.** ^(There ca
1f170 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 n only be a sing
1f180 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 le busy handler
1f190 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 defined for each
1f1a0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
1f1b0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 nnection]. Sett
1f1c0 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 ing a new busy h
1f1d0 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e andler clears an
1f1e0 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 y.** previously
1f1f0 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 set handler.)^
1f200 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 ^Note that calli
1f210 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 ng [sqlite3_busy
1f220 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f _timeout()].** o
1f230 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 r evaluating [PR
1f240 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 AGMA busy_timeou
1f250 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 t=N] will change
1f260 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e the.** busy han
1f270 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c dler and thus cl
1f280 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 ear any previous
1f290 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 ly set busy hand
1f2a0 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 ler..**.** The b
1f2b0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f usy callback sho
1f2c0 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 uld not take any
1f2d0 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d actions which m
1f2e0 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 odify the.** dat
1f2f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1f300 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
1f310 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 e busy handler.
1f320 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
1f330 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e .** the busy han
1f340 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e dler is not reen
1f350 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 trant. Any such
1f360 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 actions.** resu
1f370 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 lt in undefined
1f380 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a behavior..** .**
1f390 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 A busy handler
1f3a0 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 must not close t
1f3b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1f3c0 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 ection.** or [pr
1f3d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1f3e0 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 ] that invoked t
1f3f0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e he busy handler.
1f400 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
1f410 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c busy_handler(sql
1f420 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 ite3*,int(*)(voi
1f430 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a d*,int),void*);.
1f440 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1f450 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 Set A Busy Time
1f460 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 out.** METHOD: s
1f470 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
1f480 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 is routine sets
1f490 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f a [sqlite3_busy_
1f4a0 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 handler | busy h
1f4b0 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 andler] that sle
1f4c0 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 eps.** for a spe
1f4d0 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 cified amount of
1f4e0 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 time when a tab
1f4f0 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e le is locked. ^
1f500 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 The handler.** w
1f510 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 ill sleep multip
1f520 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 le times until a
1f530 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c t least "ms" mil
1f540 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 liseconds of sle
1f550 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 eping.** have ac
1f560 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 cumulated. ^Aft
1f570 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 er at least "ms"
1f580 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 milliseconds of
1f590 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 sleeping,.** th
1f5a0 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e e handler return
1f5b0 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 s 0 which causes
1f5c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1f5d0 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b ] to return.** [
1f5e0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a SQLITE_BUSY]..**
1f5f0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 .** ^Calling thi
1f600 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 s routine with a
1f610 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 n argument less
1f620 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f than or equal to
1f630 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f zero.** turns o
1f640 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 ff all busy hand
1f650 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 lers..**.** ^(Th
1f660 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ere can only be
1f670 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 a single busy ha
1f680 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 ndler for a part
1f690 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
1f6a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1f6b0 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d at any given mom
1f6c0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 ent. If another
1f6d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a busy handler.**
1f6e0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 was defined (u
1f6f0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 sing [sqlite3_bu
1f700 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 sy_handler()]) p
1f710 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a rior to calling.
1f720 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c ** this routine,
1f730 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 that other busy
1f740 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 handler is clea
1f750 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 red.)^.**.** See
1f760 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 also: [PRAGMA
1f770 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f busy_timeout].*/
1f780 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 .int sqlite3_bus
1f790 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 y_timeout(sqlite
1f7a0 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 3*, int ms);../*
1f7b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
1f7c0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e nvenience Routin
1f7d0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 es For Running Q
1f7e0 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 ueries.** METHOD
1f7f0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
1f800 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 This is a legacy
1f810 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 interface that
1f820 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 is preserved for
1f830 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
1f840 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 tibility..** Use
1f850 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 of this interfa
1f860 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d ce is not recomm
1f870 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 ended..**.** Def
1f880 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 inition: A <b>re
1f890 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 sult table</b> i
1f8a0 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 s memory data st
1f8b0 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 ructure created
1f8c0 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 by the.** [sqlit
1f8d0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 e3_get_table()]
1f8e0 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 interface. A re
1f8f0 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 sult table recor
1f900 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 ds the.** comple
1f910 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 te query results
1f920 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 from one or mor
1f930 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a e queries..**.**
1f940 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 The table conce
1f950 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 ptually has a nu
1f960 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 mber of rows and
1f970 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a columns. But.*
1f980 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 * these numbers
1f990 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 are not part of
1f9a0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
1f9b0 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a itself. These.
1f9c0 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f ** numbers are o
1f9d0 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 btained separate
1f9e0 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 ly. Let N be th
1f9f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 e number of rows
1fa00 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 .** and M be the
1fa10 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
1fa20 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 ns..**.** A resu
1fa30 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 lt table is an a
1fa40 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 rray of pointers
1fa50 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 to zero-termina
1fa60 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 ted UTF-8 string
1fa70 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 s..** There are
1fa80 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 (N+1)*M elements
1fa90 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 in the array.
1faa0 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e The first M poin
1fab0 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f ters point.** to
1fac0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1fad0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 strings that c
1fae0 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 ontain the names
1faf0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e of the columns.
1fb00 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e .** The remainin
1fb10 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f g entries all po
1fb20 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 int to query res
1fb30 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 ults. NULL valu
1fb40 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 es result.** in
1fb50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 NULL pointers.
1fb60 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 All other values
1fb70 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 are in their UT
1fb80 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 F-8 zero-termina
1fb90 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 ted.** string re
1fba0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 presentation as
1fbb0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
1fbc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
1fbd0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 ()]..**.** A res
1fbe0 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 ult table might
1fbf0 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f consist of one o
1fc00 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c r more memory al
1fc10 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 locations..** It
1fc20 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
1fc30 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 pass a result ta
1fc40 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 ble directly to
1fc50 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1fc60 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 ..** A result ta
1fc70 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 ble should be de
1fc80 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 allocated using
1fc90 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 [sqlite3_free_ta
1fca0 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ble()]..**.** ^(
1fcb0 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 As an example of
1fcc0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
1fcd0 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 e format, suppos
1fce0 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 e a query result
1fcf0 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 .** is as follow
1fd00 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
1fd10 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 uote><pre>.**
1fd20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 Name
1fd30 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 | Age.**
1fd40 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ---------------
1fd50 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 --------.**
1fd60 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c Alice |
1fd70 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 43.** Bo
1fd80 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a b | 28.*
1fd90 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 * Cindy
1fda0 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 | 21.** </p
1fdb0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1fdc0 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 .**.** There are
1fdd0 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d two column (M==
1fde0 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 2) and three row
1fdf0 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 s (N==3). Thus
1fe00 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 the.** result ta
1fe10 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 ble has 8 entrie
1fe20 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 s. Suppose the
1fe30 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 result table is
1fe40 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 stored.** in an
1fe50 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 array names azRe
1fe60 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 sult. Then azRe
1fe70 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 sult holds this
1fe80 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c content:.**.** <
1fe90 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1fea0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
1feb0 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 ult[0] = "Na
1fec0 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 me";.** a
1fed0 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d zResult[1] =
1fee0 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 "Age";.**
1fef0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 azResult[2
1ff00 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 ] = "Alice";.**
1ff10 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
1ff20 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a #91;3] = "43";.*
1ff30 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1ff40 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 t[4] = "Bob"
1ff50 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
1ff60 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 sult[5] = "2
1ff70 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 8";.** az
1ff80 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 Result[6] =
1ff90 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 "Cindy";.**
1ffa0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1ffb0 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 7] = "21";.** </
1ffc0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1ffd0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 >)^.**.** ^The s
1ffe0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
1fff0 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c () function eval
20000 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 uates one or mor
20010 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 e.** semicolon-s
20020 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 eparated SQL sta
20030 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a tements in the z
20040 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
20050 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f TF-8.** string o
20060 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 f its 2nd parame
20070 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ter and returns
20080 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 a result table t
20090 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 o the.** pointer
200a0 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 given in its 3r
200b0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a d parameter..**.
200c0 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 ** After the app
200d0 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e lication has fin
200e0 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 ished with the r
200f0 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 esult from sqlit
20100 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a e3_get_table(),.
20110 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 ** it must pass
20120 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
20130 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 pointer to sqli
20140 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
20150 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 in order to.**
20160 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f release the memo
20170 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c ry that was mall
20180 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f oced. Because o
20190 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a f the way the.**
201a0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
201b0 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 ()] happens with
201c0 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 in sqlite3_get_t
201d0 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c able(), the call
201e0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ing.** function
201f0 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 must not try to
20200 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 call [sqlite3_fr
20210 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 ee()] directly.
20220 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 Only.** [sqlite
20230 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 3_free_table()]
20240 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 is able to relea
20250 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 se the memory pr
20260 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c operly and safel
20270 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c y..**.** The sql
20280 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
20290 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d interface is im
202a0 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 plemented as a w
202b0 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a rapper around.**
202c0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
202d0 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f ]. The sqlite3_
202e0 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 get_table() rout
202f0 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 ine does not hav
20300 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 e access.** to a
20310 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 ny internal data
20320 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 structures of S
20330 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 QLite. It uses
20340 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a only the public.
20350 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 ** interface def
20360 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 ined here. As a
20370 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 consequence, er
20380 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 rors that occur
20390 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 in the.** wrappe
203a0 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 r layer outside
203b0 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 of the internal
203c0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
203d0 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a call are not.**
203e0 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 reflected in su
203f0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
20400 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f o [sqlite3_errco
20410 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c de()] or.** [sql
20420 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a ite3_errmsg()]..
20430 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 */.int sqlite3_g
20440 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 et_table(. sqli
20450 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
20460 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 /* An open dat
20470 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 abase */. const
20480 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 char *zSql,
20490 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 /* SQL to be ev
204a0 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 aluated */. cha
204b0 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 r ***pazResult,
204c0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 /* Results of
204d0 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 the query */.
204e0 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 int *pnRow,
204f0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 /* Number
20500 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 of result rows w
20510 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 ritten here */.
20520 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 int *pnColumn,
20530 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 /* Number
20540 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d of result colum
20550 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 ns written here
20560 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 */. char **pzEr
20570 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 rmsg /* Er
20580 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 ror msg written
20590 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 here */.);.void
205a0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
205b0 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 le(char **result
205c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
205d0 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 EF: Formatted St
205e0 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 ring Printing Fu
205f0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 nctions.**.** Th
20600 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
20610 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 work-alikes of
20620 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 the "printf()" f
20630 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f amily of functio
20640 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 ns.** from the s
20650 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
20660 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 y..** These rout
20670 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 ines understand
20680 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d most of the comm
20690 6f 6e 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 on formatting op
206a0 74 69 6f 6e 73 20 66 72 6f 6d 0a 2a 2a 20 74 68 tions from.** th
206b0 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 e standard libra
206c0 72 79 20 70 72 69 6e 74 66 28 29 20 0a 2a 2a 20 ry printf() .**
206d0 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 plus some additi
206e0 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 onal non-standar
206f0 64 20 66 6f 72 6d 61 74 73 20 28 5b 25 71 5d 2c d formats ([%q],
20700 20 5b 25 51 5d 2c 20 5b 25 77 5d 2c 20 61 6e 64 [%Q], [%w], and
20710 20 5b 25 7a 5d 29 2e 0a 2a 2a 20 53 65 65 20 74 [%z])..** See t
20720 68 65 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69 he [built-in pri
20730 6e 74 66 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 ntf()] documenta
20740 74 69 6f 6e 20 66 6f 72 20 64 65 74 61 69 6c 73 tion for details
20750 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
20760 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 ite3_mprintf() a
20770 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 nd sqlite3_vmpri
20780 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 ntf() routines w
20790 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 rite their.** re
207a0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 sults into memor
207b0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
207c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 [sqlite3_malloc6
207d0 34 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 4()]..** The str
207e0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 ings returned by
207f0 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 these two routi
20800 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a nes should be.**
20810 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 released by [sq
20820 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 lite3_free()].
20830 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 ^Both routines r
20840 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 eturn a.** NULL
20850 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 pointer if [sqli
20860 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 20 te3_malloc64()]
20870 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c is unable to all
20880 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 ocate enough.**
20890 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 memory to hold t
208a0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 he resulting str
208b0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ing..**.** ^(The
208c0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
208d0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 f() routine is s
208e0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 imilar to "snpri
208f0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 ntf()" from.** t
20900 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 he standard C li
20910 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 brary. The resu
20920 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e lt is written in
20930 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 to the.** buffer
20940 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 supplied as the
20950 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
20960 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 r whose size is
20970 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 given by.** the
20980 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e first parameter.
20990 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f Note that the o
209a0 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 rder of the.** f
209b0 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 irst two paramet
209c0 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 ers is reversed
209d0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e from snprintf().
209e0 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a )^ This is an.*
209f0 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 * historical acc
20a00 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f ident that canno
20a10 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f t be fixed witho
20a20 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 ut breaking.** b
20a30 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
20a40 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 bility. ^(Note
20a50 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 also that sqlite
20a60 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
20a70 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
20a80 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 r to its buffer
20a90 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e instead of the n
20aa0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 umber of.** char
20ab0 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 acters actually
20ac0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 written into the
20ad0 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 buffer.)^ We a
20ae0 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 dmit that.** the
20af0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 number of chara
20b00 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f cters written wo
20b10 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 uld be a more us
20b20 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 eful return.** v
20b30 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e alue but we cann
20b40 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d ot change the im
20b50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
20b60 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
20b70 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 ().** now withou
20b80 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 t breaking compa
20b90 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 tibility..**.**
20ba0 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 ^As long as the
20bb0 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 buffer size is g
20bc0 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f reater than zero
20bd0 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e , sqlite3_snprin
20be0 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 tf().** guarante
20bf0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 es that the buff
20c00 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 er is always zer
20c10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e o-terminated. ^
20c20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 The first.** par
20c30 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 ameter "n" is th
20c40 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 e total size of
20c50 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c the buffer, incl
20c60 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a uding space for.
20c70 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d ** the zero term
20c80 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 inator. So the
20c90 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 longest string t
20ca0 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c hat can be compl
20cb0 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e etely.** written
20cc0 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 will be n-1 cha
20cd0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e racters..**.** ^
20ce0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 The sqlite3_vsnp
20cf0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 rintf() routine
20d00 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 is a varargs ver
20d10 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f sion of sqlite3_
20d20 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a snprintf()..**.*
20d30 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 62 75 * See also: [bu
20d40 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d ilt-in printf()]
20d50 2c 20 5b 70 72 69 6e 74 66 28 29 20 53 51 4c 20 , [printf() SQL
20d60 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2f 0a 63 68 61 function].*/.cha
20d70 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e r *sqlite3_mprin
20d80 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e tf(const char*,.
20d90 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 ..);.char *sqlit
20da0 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 e3_vmprintf(cons
20db0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 t char*, va_list
20dc0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 );.char *sqlite3
20dd0 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 _snprintf(int,ch
20de0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
20df0 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c ...);.char *sql
20e00 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 ite3_vsnprintf(i
20e10 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 nt,char*,const c
20e20 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a har*, va_list);.
20e30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
20e40 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 Memory Allocati
20e50 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a on Subsystem.**.
20e60 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f ** The SQLite co
20e70 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 re uses these th
20e80 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 ree routines for
20e90 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a all of its own.
20ea0 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f ** internal memo
20eb0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
20ec0 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 eds. "Core" in t
20ed0 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 he previous sent
20ee0 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 ence.** does not
20ef0 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 include operati
20f00 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 ng-system specif
20f10 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 ic VFS implement
20f20 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 ation. The.** W
20f30 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 indows VFS uses
20f40 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 native malloc()
20f50 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 and free() for s
20f60 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a ome operations..
20f70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
20f80 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 e3_malloc() rout
20f90 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ine returns a po
20fa0 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b inter to a block
20fb0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 .** of memory at
20fc0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 least N bytes i
20fd0 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 n length, where
20fe0 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 N is the paramet
20ff0 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 er..** ^If sqlit
21000 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 e3_malloc() is u
21010 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 nable to obtain
21020 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a sufficient free.
21030 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 ** memory, it re
21040 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
21050 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 nter. ^If the p
21060 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a arameter N to.**
21070 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
21080 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 ) is zero or neg
21090 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 ative then sqlit
210a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 e3_malloc() retu
210b0 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f rns.** a NULL po
210c0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 inter..**.** ^Th
210d0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 e sqlite3_malloc
210e0 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 64(N) routine wo
210f0 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a rks just like.**
21100 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
21110 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e N) except that N
21120 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 is an unsigned
21130 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 64-bit integer i
21140 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 nstead.** of a s
21150 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 igned 32-bit int
21160 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c eger..**.** ^Cal
21170 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 ling sqlite3_fre
21180 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 e() with a point
21190 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 er previously re
211a0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c turned.** by sql
211b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 ite3_malloc() or
211c0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
211d0 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 () releases that
211e0 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 memory so.** th
211f0 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 at it might be r
21200 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c eused. ^The sql
21210 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 ite3_free() rout
21220 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f ine is.** a no-o
21230 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 p if is called w
21240 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
21250 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e er. Passing a N
21260 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 ULL pointer.** t
21270 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 o sqlite3_free()
21280 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 is harmless. A
21290 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 fter being freed
212a0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 , memory.** shou
212b0 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 ld neither be re
212c0 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 ad nor written.
212d0 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 Even reading pr
212e0 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a eviously freed.*
212f0 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 * memory might r
21300 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 esult in a segme
21310 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 ntation fault or
21320 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 other severe er
21330 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 ror..** Memory c
21340 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 orruption, a seg
21350 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c mentation fault,
21360 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 or other severe
21370 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 error.** might
21380 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 result if sqlite
21390 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 3_free() is call
213a0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 ed with a non-NU
213b0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a LL pointer that.
213c0 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 ** was not obtai
213d0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ned from sqlite3
213e0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c _malloc() or sql
213f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
21400 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
21410 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 e3_realloc(X,N)
21420 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
21430 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a ts to resize a.*
21440 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 * prior memory a
21450 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 llocation X to b
21460 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 e at least N byt
21470 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 es..** ^If the X
21480 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
21490 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c lite3_realloc(X,
214a0 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 N).** is a NULL
214b0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 pointer then its
214c0 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 behavior is ide
214d0 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e ntical to callin
214e0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c g.** sqlite3_mal
214f0 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 loc(N)..** ^If t
21500 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 he N parameter t
21510 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
21520 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f c(X,N) is zero o
21530 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 r.** negative th
21540 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
21550 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 is exactly the s
21560 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a ame as calling.*
21570 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 * sqlite3_free(X
21580 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 )..** ^sqlite3_r
21590 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 ealloc(X,N) retu
215a0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
215b0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
215c0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 tion.** of at le
215d0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 ast N bytes in s
215e0 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 ize or NULL if i
215f0 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f nsufficient memo
21600 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e ry is available.
21610 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 .** ^If M is the
21620 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 size of the pri
21630 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 or allocation, t
21640 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 hen min(N,M) byt
21650 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 es.** of the pri
21660 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 or allocation ar
21670 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 e copied into th
21680 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 e beginning of b
21690 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a uffer returned.*
216a0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 * by sqlite3_rea
216b0 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 lloc(X,N) and th
216c0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
216d0 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 on is freed..**
216e0 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c ^If sqlite3_real
216f0 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 loc(X,N) returns
21700 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 NULL and N is p
21710 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 ositive, then th
21720 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 e.** prior alloc
21730 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 ation is not fre
21740 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
21750 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 qlite3_realloc64
21760 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 (X,N) interfaces
21770 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 works the same
21780 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 as.** sqlite3_re
21790 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 alloc(X,N) excep
217a0 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 t that N is a 64
217b0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e -bit unsigned in
217c0 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a teger instead.**
217d0 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 of a 32-bit sig
217e0 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a ned integer..**.
217f0 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 ** ^If X is a me
21800 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
21810 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 previously obtai
21820 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ned from sqlite3
21830 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 _malloc(),.** sq
21840 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 lite3_malloc64()
21850 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f , sqlite3_reallo
21860 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f c(), or sqlite3_
21870 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 realloc64(), the
21880 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 n.** sqlite3_msi
21890 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 ze(X) returns th
218a0 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d e size of that m
218b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
218c0 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 in bytes..** ^T
218d0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
218e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 d by sqlite3_msi
218f0 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c ze(X) might be l
21900 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e arger than the n
21910 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 umber.** of byte
21920 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e s requested when
21930 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 X was allocated
21940 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 . ^If X is a NU
21950 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a LL pointer then.
21960 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 ** sqlite3_msize
21970 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f (X) returns zero
21980 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 . If X points t
21990 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 o something that
219a0 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 is not.** the b
219b0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f eginning of memo
219c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f ry allocation, o
219d0 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 r if it points t
219e0 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 o a formerly.**
219f0 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c valid memory all
21a00 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 ocation that has
21a10 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c now been freed,
21a20 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
21a30 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 or.** of sqlite3
21a40 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 _msize(X) is und
21a50 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 efined and possi
21a60 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a bly harmful..**.
21a70 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 ** ^The memory r
21a80 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
21a90 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c e3_malloc(), sql
21aa0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a ite3_realloc(),.
21ab0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f ** sqlite3_mallo
21ac0 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 c64(), and sqlit
21ad0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a e3_realloc64().*
21ae0 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 * is always alig
21af0 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 ned to at least
21b00 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 an 8 byte bounda
21b10 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 ry, or to a.** 4
21b20 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 byte boundary i
21b30 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f f the [SQLITE_4_
21b40 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c BYTE_ALIGNED_MAL
21b50 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d LOC] compile-tim
21b60 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 e.** option is u
21b70 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 sed..**.** In SQ
21b80 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
21b90 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 .0 and 3.5.1, it
21ba0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f was possible to
21bb0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 define.** the S
21bc0 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 QLITE_OMIT_MEMOR
21bd0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 Y_ALLOCATION whi
21be0 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 ch would cause t
21bf0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 he built-in.** i
21c00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
21c10 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
21c20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 to be omitted.
21c30 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a That capability.
21c40 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 ** is no longer
21c50 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 provided. Only
21c60 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
21c70 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 allocators can b
21c80 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 e used..**.** Pr
21c90 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 ior to SQLite ve
21ca0 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 rsion 3.7.10, th
21cb0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 e Windows OS int
21cc0 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c erface layer cal
21cd0 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 led.** the syste
21ce0 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 m malloc() and f
21cf0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 ree() directly w
21d00 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a hen converting.*
21d10 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 * filenames betw
21d20 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e een the UTF-8 en
21d30 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 coding used by S
21d40 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 QLite.** and wha
21d50 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 tever filename e
21d60 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 ncoding is used
21d70 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 by the particula
21d80 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 r Windows.** ins
21d90 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f tallation. Memo
21da0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 ry allocation er
21db0 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 rors were detect
21dc0 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 ed, but.** they
21dd0 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 were reported ba
21de0 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 ck as [SQLITE_CA
21df0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 NTOPEN] or.** [S
21e00 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 QLITE_IOERR] rat
21e10 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
21e20 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 _NOMEM]..**.** T
21e30 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d he pointer argum
21e40 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 ents to [sqlite3
21e50 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 _free()] and [sq
21e60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
21e70 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 .** must be eith
21e80 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 er NULL or else
21e90 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 pointers obtaine
21ea0 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a d from a prior.*
21eb0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 * invocation of
21ec0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
21ed0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
21ee0 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 ealloc()] that h
21ef0 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 ave.** not yet b
21f00 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a een released..**
21f10 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
21f20 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 ion must not rea
21f30 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 d or write any p
21f40 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 art of.** a bloc
21f50 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 k of memory afte
21f60 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 r it has been re
21f70 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 leased using.**
21f80 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
21f90 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
21fa0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 lloc()]..*/.void
21fb0 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 *sqlite3_malloc
21fc0 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c (int);.void *sql
21fd0 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 ite3_malloc64(sq
21fe0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 lite3_uint64);.v
21ff0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 oid *sqlite3_rea
22000 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 lloc(void*, int)
22010 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f ;.void *sqlite3_
22020 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c realloc64(void*,
22030 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 sqlite3_uint64)
22040 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 ;.void sqlite3_f
22050 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 ree(void*);.sqli
22060 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 te3_uint64 sqlit
22070 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b e3_msize(void*);
22080 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
22090 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
220a0 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a or Statistics.**
220b0 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 .** SQLite provi
220c0 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e des these two in
220d0 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 terfaces for rep
220e0 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 orting on the st
220f0 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b atus.** of the [
22100 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
22110 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ], [sqlite3_free
22120 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
22130 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 3_realloc()].**
22140 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 routines, which
22150 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 form the built-i
22160 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
22170 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a ion subsystem..*
22180 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 *.** ^The [sqlit
22190 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
221a0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ] routine return
221b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
221c0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f bytes.** of memo
221d0 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 ry currently out
221e0 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 standing (malloc
221f0 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 ed but not freed
22200 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 )..** ^The [sqli
22210 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
22220 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 ater()] routine
22230 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 returns the maxi
22240 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 mum.** value of
22250 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
22260 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 used()] since th
22270 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 e high-water mar
22280 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 k.** was last re
22290 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 set. ^The value
222a0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
222b0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
222c0 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 ed()] and.** [sq
222d0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
222e0 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 hwater()] includ
222f0 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a e any overhead.*
22300 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 * added by SQLit
22310 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 e in its impleme
22320 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 ntation of [sqli
22330 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a te3_malloc()],.*
22340 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 * but not overhe
22350 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 ad added by the
22360 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 any underlying s
22370 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a ystem library.**
22380 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b routines that [
22390 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
223a0 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a ] may call..**.*
223b0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 * ^The memory hi
223c0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 gh-water mark is
223d0 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 reset to the cu
223e0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a rrent value of.*
223f0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 * [sqlite3_memor
22400 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 y_used()] if and
22410 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 only if the par
22420 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 ameter to.** [sq
22430 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
22440 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 hwater()] is tru
22450 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 e. ^The value r
22460 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 eturned.** by [s
22470 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
22480 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 ghwater(1)] is t
22490 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 he high-water ma
224a0 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 rk.** prior to t
224b0 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c he reset..*/.sql
224c0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
224d0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 e3_memory_used(v
224e0 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e oid);.sqlite3_in
224f0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f t64 sqlite3_memo
22500 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 ry_highwater(int
22510 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a resetFlag);../*
22520 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 .** CAPI3REF: Ps
22530 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 eudo-Random Numb
22540 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a er Generator.**.
22550 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 ** SQLite contai
22560 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 ns a high-qualit
22570 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 y pseudo-random
22580 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 number generator
22590 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a (PRNG) used to.
225a0 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d ** select random
225b0 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 [ROWID | ROWIDs
225c0 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 ] when inserting
225d0 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 new records int
225e0 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a o a table that.*
225f0 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 * already uses t
22600 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 he largest possi
22610 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 ble [ROWID]. Th
22620 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 e PRNG is also u
22630 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 sed for.** the b
22640 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 uild-in random()
22650 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 and randomblob(
22660 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e ) SQL functions.
22670 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 This interface
22680 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 allows.** appli
22690 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 cations to acces
226a0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 s the same PRNG
226b0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 for other purpos
226c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c es..**.** ^A cal
226d0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e l to this routin
226e0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 e stores N bytes
226f0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 of randomness i
22700 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a nto buffer P..**
22710 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 ^The P paramete
22720 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 r can be a NULL
22730 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e pointer..**.** ^
22740 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 If this routine
22750 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 has not been pre
22760 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f viously called o
22770 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 r if the previou
22780 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 s.** call had N
22790 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 less than one or
227a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
227b0 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 for P, then the
227c0 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 PRNG is.** seede
227d0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 d using randomne
227e0 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ss obtained from
227f0 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 the xRandomness
22800 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 method of.** th
22810 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
22820 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a e3_vfs] object..
22830 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 ** ^If the previ
22840 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 ous call to this
22850 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 routine had an
22860 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 N of 1 or more a
22870 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c nd a.** non-NULL
22880 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 P then the pseu
22890 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 do-randomness is
228a0 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e generated.** in
228b0 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 ternally and wit
228c0 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f hout recourse to
228d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
228e0 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a s] xRandomness.*
228f0 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 * method..*/.voi
22900 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d d sqlite3_random
22910 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 ness(int N, void
22920 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *P);../*.** CAP
22930 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 I3REF: Compile-T
22940 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f ime Authorizatio
22950 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d n Callbacks.** M
22960 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
22970 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 * KEYWORDS: {aut
22980 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
22990 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f }.**.** ^This ro
229a0 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 utine registers
229b0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 an authorizer ca
229c0 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 llback with a pa
229d0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 rticular.** [dat
229e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
229f0 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 ], supplied in t
22a00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
22a10 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f t..** ^The autho
22a20 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
22a30 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c s invoked as SQL
22a40 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 statements are
22a50 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a being compiled.*
22a60 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 * by [sqlite3_pr
22a70 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 epare()] or its
22a80 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 variants [sqlite
22a90 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 3_prepare_v2()],
22aa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
22ab0 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c pare_v3()], [sql
22ac0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
22ad0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ], [sqlite3_prep
22ae0 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 are16_v2()],.**
22af0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
22b00 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e pare16_v3()]. ^
22b10 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f At various.** po
22b20 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 ints during the
22b30 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 compilation proc
22b40 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 ess, as logic is
22b50 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a being created.*
22b60 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 * to perform var
22b70 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 ious actions, th
22b80 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
22b90 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
22ba0 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 to.** see if th
22bb0 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 ose actions are
22bc0 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 allowed. ^The a
22bd0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
22be0 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 ck should.** ret
22bf0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
22c00 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 to allow the act
22c10 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e ion, [SQLITE_IGN
22c20 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 ORE] to disallow
22c30 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 the.** specific
22c40 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f action but allo
22c50 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d w the SQL statem
22c60 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 ent to continue
22c70 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 to be.** compile
22c80 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 d, or [SQLITE_DE
22c90 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 NY] to cause the
22ca0 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 entire SQL stat
22cb0 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 ement to be.** r
22cc0 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 ejected with an
22cd0 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 error. ^If the
22ce0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
22cf0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 ack returns.** a
22d00 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 ny value other t
22d10 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f han [SQLITE_IGNO
22d20 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d RE], [SQLITE_OK]
22d30 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e , or [SQLITE_DEN
22d40 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b Y].** then the [
22d50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
22d60 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c v2()] or equival
22d70 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 ent call that tr
22d80 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 iggered.** the a
22d90 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 uthorizer will f
22da0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f ail with an erro
22db0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a r message..**.**
22dc0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 When the callba
22dd0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
22de0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 TE_OK], that mea
22df0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e ns the operation
22e00 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 .** requested is
22e10 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 ok. ^When the
22e20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
22e30 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 [SQLITE_DENY],
22e40 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
22e50 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
22e60 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c equivalent call
22e70 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 that triggered
22e80 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 the.** authorize
22e90 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 r will fail with
22ea0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
22eb0 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 e explaining tha
22ec0 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 t.** access is d
22ed0 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 enied. .**.** ^T
22ee0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
22ef0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 er to the author
22f00 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
22f10 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 a copy of the t
22f20 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 hird.** paramete
22f30 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
22f40 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
22f50 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 ) interface. ^Th
22f60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
22f70 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c er.** to the cal
22f80 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 lback is an inte
22f90 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 ger [SQLITE_COPY
22fa0 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 | action code]
22fb0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a that specifies.*
22fc0 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 * the particular
22fd0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 action to be au
22fe0 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 thorized. ^The t
22ff0 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 hird through six
23000 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a th parameters.**
23010 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
23020 20 61 72 65 20 65 69 74 68 65 72 20 4e 55 4c 4c are either NULL
23030 20 70 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 pointers or zer
23040 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 o-terminated str
23050 69 6e 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e ings.** that con
23060 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 tain additional
23070 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 details about th
23080 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 e action to be a
23090 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 uthorized..** Ap
230a0 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 plications must
230b0 61 6c 77 61 79 73 20 62 65 20 70 72 65 70 61 72 always be prepar
230c0 65 64 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 ed to encounter
230d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
230e0 6e 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 n any.** of the
230f0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 74 68 third through th
23100 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 e sixth paramete
23110 72 73 20 6f 66 20 74 68 65 20 61 75 74 68 6f 72 rs of the author
23120 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b ization callback
23130 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
23140 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b action code is [
23150 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 SQLITE_READ].**
23160 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b and the callback
23170 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
23180 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 _IGNORE] then th
23190 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
231a0 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d tatement] statem
231b0 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 ent is construct
231c0 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 ed to substitute
231d0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 .** a NULL value
231e0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 in place of the
231f0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 table column th
23200 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a at would have.**
23210 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 been read if [S
23220 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 QLITE_OK] had be
23230 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 en returned. Th
23240 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 e [SQLITE_IGNORE
23250 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 ].** return can
23260 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 be used to deny
23270 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 an untrusted use
23280 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 r access to indi
23290 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e vidual.** column
232a0 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a s of a table..**
232b0 20 5e 57 68 65 6e 20 61 20 74 61 62 6c 65 20 69 ^When a table i
232c0 73 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 s referenced by
232d0 61 20 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 6e a [SELECT] but n
232e0 6f 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 o column values
232f0 61 72 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 are.** extracted
23300 20 66 72 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 from that table
23310 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e (for example in
23320 20 61 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a a query like.**
23330 20 22 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a "SELECT count(*
23340 29 20 46 52 4f 4d 20 74 61 62 22 29 20 74 68 65 ) FROM tab") the
23350 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 n the [SQLITE_RE
23360 41 44 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 63 AD] authorizer c
23370 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e allback.** is in
23380 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 voked once for t
23390 68 61 74 20 74 61 62 6c 65 20 77 69 74 68 20 61 hat table with a
233a0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 column name tha
233b0 74 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 t is an empty st
233c0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ring..** ^If the
233d0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 action code is
233e0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 [SQLITE_DELETE]
233f0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b and the callback
23400 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c returns.** [SQL
23410 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e ITE_IGNORE] then
23420 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 the [DELETE] op
23430 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 eration proceeds
23440 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 but the.** [tru
23450 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 ncate optimizati
23460 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 on] is disabled
23470 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 and all rows are
23480 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 deleted individ
23490 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 ually..**.** An
234a0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 authorizer is us
234b0 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 ed when [sqlite3
234c0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 _prepare | prepa
234d0 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 ring].** SQL sta
234e0 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 tements from an
234f0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
23500 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 , to ensure that
23510 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
23520 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 nts.** do not tr
23530 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 y to access data
23540 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c they are not al
23550 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 lowed to see, or
23560 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f that they do no
23570 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 t.** try to exec
23580 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 ute malicious st
23590 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 atements that da
235a0 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 mage the databas
235b0 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 e. For.** examp
235c0 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 le, an applicati
235d0 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 on may allow a u
235e0 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 ser to enter arb
235f0 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 itrary.** SQL qu
23600 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 eries for evalua
23610 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 tion by a databa
23620 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 se. But the app
23630 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a lication does.**
23640 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 not want the us
23650 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f er to be able to
23660 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 make arbitrary
23670 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a changes to the.*
23680 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 * database. An
23690 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 authorizer could
236a0 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 then be put in
236b0 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a place while the.
236c0 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 ** user-entered
236d0 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 SQL is being [sq
236e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 lite3_prepare |
236f0 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a prepared] that.*
23700 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 * disallows ever
23710 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 ything except [S
23720 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
23730 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 s..**.** Applica
23740 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 tions that need
23750 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 to process SQL f
23760 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f rom untrusted so
23770 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 urces.** might a
23780 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 lso consider low
23790 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c ering resource l
237a0 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c imits using [sql
237b0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a ite3_limit()].**
237c0 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 and limiting da
237d0 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e tabase size usin
237e0 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f g the [max_page_
237f0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a count] [PRAGMA].
23800 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 ** in addition t
23810 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f o using an autho
23820 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f rizer..**.** ^(O
23830 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 nly a single aut
23840 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 horizer can be i
23850 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 n place on a dat
23860 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
23870 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 .** at a time.
23880 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c Each call to sql
23890 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
238a0 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 zer overrides th
238b0 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 e.** previous ca
238c0 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 ll.)^ ^Disable
238d0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 the authorizer b
238e0 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e y installing a N
238f0 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a ULL callback..**
23900 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 The authorizer
23910 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 is disabled by d
23920 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 efault..**.** Th
23930 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
23940 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 lback must not d
23950 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
23960 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
23970 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
23980 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
23990 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a ked the authoriz
239a0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 er callback..**
239b0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 Note that [sqlit
239c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
239d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 and [sqlite3_st
239e0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 ep()] both modif
239f0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 y their.** datab
23a00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
23a10 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 for the meaning
23a20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 of "modify" in t
23a30 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a his paragraph..*
23a40 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 *.** ^When [sqli
23a50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
23a60 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 ] is used to pre
23a70 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 pare a statement
23a80 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 , the.** stateme
23a90 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 nt might be re-p
23aa0 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b repared during [
23ab0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
23ac0 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 due to a .** sch
23ad0 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e ema change. Hen
23ae0 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 ce, the applicat
23af0 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 ion should ensur
23b00 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f e that the.** co
23b10 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 rrect authorizer
23b20 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e callback remain
23b30 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e s in place durin
23b40 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 g the [sqlite3_s
23b50 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e tep()]..**.** ^N
23b60 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 ote that the aut
23b70 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
23b80 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 is invoked only
23b90 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 during.** [sqli
23ba0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
23bb0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 r its variants.
23bc0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 Authorization i
23bd0 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d s not.** perform
23be0 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d ed during statem
23bf0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 ent evaluation i
23c00 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 n [sqlite3_step(
23c10 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 )], unless.** as
23c20 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 stated in the p
23c30 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 revious paragrap
23c40 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 h, sqlite3_step(
23c50 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c ) invokes.** sql
23c60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
23c70 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 ) to reprepare a
23c80 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 statement after
23c90 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 a schema change
23ca0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
23cb0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
23cc0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 . sqlite3*,. i
23cd0 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 nt (*xAuth)(void
23ce0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 *,int,const char
23cf0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f *,const char*,co
23d00 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
23d10 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a char*),. void *
23d20 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a pUserData.);../*
23d30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 .** CAPI3REF: Au
23d40 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 thorizer Return
23d50 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Codes.**.** The
23d60 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
23d70 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 horizer | author
23d80 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 izer callback fu
23d90 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 nction] must.**
23da0 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 return either [S
23db0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 QLITE_OK] or one
23dc0 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f of these two co
23dd0 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 nstants in order
23de0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 .** to signal SQ
23df0 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 Lite whether or
23e00 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 not the action i
23e10 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 s permitted. Se
23e20 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 e the.** [sqlite
23e30 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
23e40 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f | authorizer do
23e50 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 cumentation] for
23e60 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 additional.** i
23e70 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
23e80 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 * Note that SQLI
23e90 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 TE_IGNORE is als
23ea0 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e o used as a [con
23eb0 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e flict resolution
23ec0 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e mode].** return
23ed0 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c ed from the [sql
23ee0 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e ite3_vtab_on_con
23ef0 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 flict()] interfa
23f00 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ce..*/.#define S
23f10 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 QLITE_DENY 1
23f20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 /* Abort the SQ
23f30 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 L statement with
23f40 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 an error */.#de
23f50 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f fine SQLITE_IGNO
23f60 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 RE 2 /* Don't
23f70 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 allow access, bu
23f80 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 t don't generate
23f90 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a an error */../*
23fa0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 .** CAPI3REF: Au
23fb0 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 thorizer Action
23fc0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Codes.**.** The
23fd0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
23fe0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 horizer()] inter
23ff0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 face registers a
24000 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
24010 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e on.** that is in
24020 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 voked to authori
24030 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 ze certain SQL s
24040 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 tatement actions
24050 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 . The.** second
24060 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
24070 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e e callback is an
24080 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 integer code th
24090 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 at specifies.**
240a0 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 what action is b
240b0 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e eing authorized.
240c0 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 These are the
240d0 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 integer action c
240e0 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 odes that.** the
240f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
24100 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 back may be pass
24110 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ed..**.** These
24120 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 action code valu
24130 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 es signify what
24140 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f kind of operatio
24150 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 n is to be.** au
24160 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 thorized. The 3
24170 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d rd and 4th param
24180 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 eters to the aut
24190 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 horization.** ca
241a0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
241b0 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 will be paramete
241c0 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e rs or NULL depen
241d0 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 ding on which of
241e0 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 these.** codes
241f0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 is used as the s
24200 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e econd parameter.
24210 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 ^(The 5th para
24220 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 meter to the.**
24230 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
24240 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 ack is the name
24250 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
24260 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c ("main", "temp",
24270 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 .** etc.) if app
24280 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 licable.)^ ^The
24290 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6th parameter t
242a0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 o the authorizer
242b0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
242c0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
242d0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 inner-most trigg
242e0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 er or view that
242f0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
24300 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 or.** the access
24310 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c attempt or NULL
24320 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 if this access
24330 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 attempt is direc
24340 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d tly from.** top-
24350 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a level SQL code..
24360 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a */./************
24370 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
24380 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 ***************
24390 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 3rd ************
243a0 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 4th ***********
243b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
243c0 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 _CREATE_INDEX
243d0 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 1 /* In
243e0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
243f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
24400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
24410 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 CREATE_TABLE
24420 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 2 /* Tab
24430 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
24440 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
24450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
24460 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 REATE_TEMP_INDEX
24470 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 3 /* Inde
24480 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
24490 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
244a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
244b0 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 EATE_TEMP_TABLE
244c0 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 4 /* Table
244d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
244e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
244f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
24500 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 ATE_TEMP_TRIGGER
24510 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 5 /* Trigge
24520 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
24530 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
24540 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
24550 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 TE_TEMP_VIEW
24560 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6 /* View Na
24570 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
24580 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
24590 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
245a0 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 E_TRIGGER
245b0 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 7 /* Trigger
245c0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
245d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
245e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
245f0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 _VIEW
24600 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 8 /* View Name
24610 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
24620 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
24630 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 e SQLITE_DELETE
24640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 9
24650 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
24660 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
24670 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
24680 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 SQLITE_DROP_IND
24690 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 EX 10
246a0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
246b0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
246c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
246d0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c SQLITE_DROP_TABL
246e0 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 E 11
246f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
24700 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
24710 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
24720 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
24730 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 INDEX 12
24740 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
24750 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
24760 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
24770 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 LITE_DROP_TEMP_T
24780 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f ABLE 13 /
24790 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
247a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
247b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
247c0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 ITE_DROP_TEMP_TR
247d0 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a IGGER 14 /*
247e0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
247f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
24800 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
24810 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 TE_DROP_TEMP_VIE
24820 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 W 15 /*
24830 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
24840 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
24850 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
24860 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 E_DROP_TRIGGER
24870 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 16 /* T
24880 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
24890 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
248a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
248b0 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 _DROP_VIEW
248c0 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 17 /* Vi
248d0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
248e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
248f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
24900 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 INSERT
24910 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 18 /* Tab
24920 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
24930 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
24940 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 #define SQLITE_P
24950 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 RAGMA
24960 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 19 /* Prag
24970 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 ma Name 1st
24980 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 arg or NULL */.#
24990 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
249a0 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AD
249b0 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 /* Table
249c0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d Name Colum
249d0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 n Name */.#d
249e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c efine SQLITE_SEL
249f0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 ECT
24a00 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 21 /* NULL
24a10 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 NULL
24a20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
24a30 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e fine SQLITE_TRAN
24a40 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 SACTION
24a50 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 22 /* Operati
24a60 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 on NULL
24a70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
24a80 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 ine SQLITE_UPDAT
24a90 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
24aa0 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 23 /* Table Na
24ab0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e me Column N
24ac0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
24ad0 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 ne SQLITE_ATTACH
24ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
24af0 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 4 /* Filename
24b00 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
24b10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
24b20 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 e SQLITE_DETACH
24b30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 25
24b40 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e /* Database N
24b50 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 ame NULL
24b60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
24b70 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 SQLITE_ALTER_TA
24b80 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 BLE 26
24b90 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 /* Database Na
24ba0 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 me Table Name
24bb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
24bc0 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 SQLITE_REINDEX
24bd0 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 27
24be0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
24bf0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
24c00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
24c10 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 QLITE_ANALYZE
24c20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 28
24c30 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
24c40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
24c50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
24c60 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 LITE_CREATE_VTAB
24c70 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f LE 29 /
24c80 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
24c90 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 Module Name
24ca0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
24cb0 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 ITE_DROP_VTABLE
24cc0 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 30 /*
24cd0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
24ce0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 Module Name
24cf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
24d00 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 TE_FUNCTION
24d10 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 31 /*
24d20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
24d30 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 Function Name
24d40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
24d50 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 E_SAVEPOINT
24d60 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 32 /* O
24d70 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 peration S
24d80 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a avepoint Name *
24d90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
24da0 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 _COPY
24db0 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 0 /* No
24dc0 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a longer used */.
24dd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
24de0 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 ECURSIVE
24df0 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 33 /* NULL
24e00 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c NULL
24e10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a */..
24e20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
24e30 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 Tracing And Prof
24e40 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a iling Functions.
24e50 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
24e60 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 e3.**.** These r
24e70 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 70 72 outines are depr
24e80 65 63 61 74 65 64 2e 20 55 73 65 20 74 68 65 20 ecated. Use the
24e90 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 [sqlite3_trace_v
24ea0 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2()] interface.*
24eb0 2a 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 * instead of the
24ec0 20 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 routines descri
24ed0 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 bed here..**.**
24ee0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
24ef0 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b egister callback
24f00 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 functions that
24f10 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a can be used for.
24f20 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 ** tracing and p
24f30 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 rofiling the exe
24f40 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 cution of SQL st
24f50 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
24f60 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 ^The callback fu
24f70 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
24f80 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 d by sqlite3_tra
24f90 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 ce() is invoked
24fa0 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 at.** various ti
24fb0 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 mes when an SQL
24fc0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 statement is bei
24fd0 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 ng run by [sqlit
24fe0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e e3_step()]..** ^
24ff0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 The sqlite3_trac
25000 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 e() callback is
25010 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 invoked with a U
25020 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f TF-8 rendering o
25030 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 f the.** SQL sta
25040 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 tement text as t
25050 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 he statement fir
25060 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 st begins execut
25070 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 ing..** ^(Additi
25080 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 onal sqlite3_tra
25090 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d ce() callbacks m
250a0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 ight occur.** as
250b0 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 each triggered
250c0 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e subprogram is en
250d0 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c tered. The call
250e0 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 backs for trigge
250f0 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 rs.** contain a
25100 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e UTF-8 SQL commen
25110 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 t that identifie
25120 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e s the trigger.)^
25130 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
25140 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 TE_TRACE_SIZE_LI
25150 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d MIT] compile-tim
25160 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 e option can be
25170 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a used to limit.**
25180 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b the length of [
25190 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d bound parameter]
251a0 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 expansion in th
251b0 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 e output of sqli
251c0 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a te3_trace()..**.
251d0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b ** ^The callback
251e0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 function regist
251f0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ered by sqlite3_
25200 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 profile() is inv
25210 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 oked.** as each
25220 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 SQL statement fi
25230 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 nishes. ^The pr
25240 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 ofile callback c
25250 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f ontains.** the o
25260 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e riginal statemen
25270 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 t text and an es
25280 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 timate of wall-c
25290 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 lock time.** of
252a0 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 how long that st
252b0 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 atement took to
252c0 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 run. ^The profi
252d0 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 le callback.** t
252e0 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 ime is in units
252f0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 of nanoseconds,
25300 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 however the curr
25310 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ent implementati
25320 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 on.** is only ca
25330 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 pable of millise
25340 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 cond resolution
25350 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 so the six least
25360 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 significant.**
25370 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 digits in the ti
25380 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 me are meaningle
25390 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 ss. Future vers
253a0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a ions of SQLite.*
253b0 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 * might provide
253c0 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 greater resoluti
253d0 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c on on the profil
253e0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 6e er callback. In
253f0 76 6f 6b 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 voking.** either
25400 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 [sqlite3_trace(
25410 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 )] or [sqlite3_t
25420 72 61 63 65 5f 76 32 28 29 5d 20 77 69 6c 6c 20 race_v2()] will
25430 63 61 6e 63 65 6c 20 74 68 65 0a 2a 2a 20 70 72 cancel the.** pr
25440 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 2e 0a ofile callback..
25450 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 */.SQLITE_DEPREC
25460 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 ATED void *sqlit
25470 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 e3_trace(sqlite3
25480 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 *,. void(*xTra
25490 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 ce)(void*,const
254a0 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a char*), void*);.
254b0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
254c0 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f D void *sqlite3_
254d0 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a profile(sqlite3*
254e0 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 ,. void(*xProf
254f0 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 ile)(void*,const
25500 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 char*,sqlite3_u
25510 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a int64), void*);.
25520 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
25530 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 SQL Trace Event
25540 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Codes.** KEYWOR
25550 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 DS: SQLITE_TRACE
25560 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
25570 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 stants identify
25580 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 classes of event
25590 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f s that can be mo
255a0 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 nitored.** using
255b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 the [sqlite3_tr
255c0 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e ace_v2()] tracin
255d0 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 4d 20 g logic. The M
255e0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b argument.** to [
255f0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 sqlite3_trace_v2
25600 28 44 2c 4d 2c 58 2c 50 29 5d 20 69 73 20 61 6e (D,M,X,P)] is an
25610 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 OR-ed combinati
25620 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 on of one or mor
25630 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c e of.** the foll
25640 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e owing constants.
25650 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 ^The first arg
25660 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 ument to the tra
25670 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 ce callback.** i
25680 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c s one of the fol
25690 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 lowing constants
256a0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 ..**.** New trac
256b0 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 ing constants ma
256c0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
256d0 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a ture releases..*
256e0 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 *.** ^A trace ca
256f0 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20 llback has four
25700 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c arguments: xCall
25710 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a back(T,C,P,X)..*
25720 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e * ^The T argumen
25730 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 t is one of the
25740 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64 integer type cod
25750 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 es above..** ^Th
25760 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 e C argument is
25770 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f a copy of the co
25780 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 ntext pointer pa
25790 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a ssed in as the.*
257a0 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e * fourth argumen
257b0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 t to [sqlite3_tr
257c0 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 ace_v2()]..** Th
257d0 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 e P and X argume
257e0 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 nts are pointers
257f0 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 whose meanings
25800 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a depend on T..**.
25810 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c ** <dl>.** [[SQL
25820 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d ITE_TRACE_STMT]]
25830 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 <dt>SQLITE_TRAC
25840 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c E_STMT</dt>.** <
25850 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 dd>^An SQLITE_TR
25860 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 ACE_STMT callbac
25870 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 k is invoked whe
25880 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 n a prepared sta
25890 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 tement.** first
258a0 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 begins running a
258b0 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f nd possibly at o
258c0 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e ther times durin
258d0 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 g the.** executi
258e0 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 on of the prepar
258f0 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 ed statement, su
25900 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61 ch as at the sta
25910 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 rt of each.** tr
25920 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d igger subprogram
25930 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e . ^The P argumen
25940 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
25950 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 o the.** [prepar
25960 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e ed statement]. ^
25970 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 The X argument i
25980 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
25990 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a string which.**
259a0 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64 is the unexpand
259b0 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74 ed SQL text of t
259c0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
259d0 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 ement or an SQL
259e0 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 comment .** that
259f0 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69 indicates the i
25a00 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 nvocation of a t
25a10 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61 rigger. ^The ca
25a20 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 llback can compu
25a30 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 te.** the same t
25a40 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68 ext that would h
25a50 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 ave been returne
25a60 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20 d by the legacy
25a70 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 [sqlite3_trace()
25a80 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 ].** interface b
25a90 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72 y using the X ar
25aa0 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65 gument when X be
25ab0 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61 gins with "--" a
25ac0 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b nd invoking.** [
25ad0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 sqlite3_expanded
25ae0 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 _sql(P)] otherwi
25af0 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 se..**.** [[SQLI
25b00 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 TE_TRACE_PROFILE
25b10 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 ]] <dt>SQLITE_TR
25b20 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e ACE_PROFILE</dt>
25b30 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 .** <dd>^An SQLI
25b40 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 TE_TRACE_PROFILE
25b50 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 callback provid
25b60 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 es approximately
25b70 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 the same.** inf
25b80 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70 ormation as is p
25b90 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b rovided by the [
25ba0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 sqlite3_profile(
25bb0 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 )] callback..**
25bc0 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 ^The P argument
25bd0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
25be0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
25bf0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 atement] and the
25c00 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70 .** X argument p
25c10 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69 oints to a 64-bi
25c20 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 t integer which
25c30 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 is the estimated
25c40 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 of.** the numbe
25c50 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 r of nanosecond
25c60 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 that the prepare
25c70 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b d statement took
25c80 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 to run..** ^The
25c90 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 SQLITE_TRACE_PR
25ca0 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 OFILE callback i
25cb0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 s invoked when t
25cc0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e he statement fin
25cd0 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 ishes..**.** [[S
25ce0 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d QLITE_TRACE_ROW]
25cf0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 ] <dt>SQLITE_TRA
25d00 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c CE_ROW</dt>.** <
25d10 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 dd>^An SQLITE_TR
25d20 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b ACE_ROW callback
25d30 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e is invoked when
25d40 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a ever a prepared.
25d50 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e ** statement gen
25d60 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20 erates a single
25d70 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 row of result.
25d80 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d .** ^The P argum
25d90 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
25da0 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 to the [prepare
25db0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 d statement] and
25dc0 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 the.** X argume
25dd0 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a nt is unused..**
25de0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 .** [[SQLITE_TRA
25df0 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 CE_CLOSE]] <dt>S
25e00 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 QLITE_TRACE_CLOS
25e10 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 E</dt>.** <dd>^A
25e20 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 n SQLITE_TRACE_C
25e30 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 LOSE callback is
25e40 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 invoked when a
25e50 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
25e60 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a ection closes..*
25e70 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e * ^The P argumen
25e80 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
25e90 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 o the [database
25ea0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 connection] obje
25eb0 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 ct.** and the X
25ec0 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 argument is unus
25ed0 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a ed..** </dl>.*/.
25ee0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
25ef0 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20 RACE_STMT
25f00 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 0x01.#define SQL
25f10 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c ITE_TRACE_PROFIL
25f20 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e E 0x02.#defin
25f30 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 e SQLITE_TRACE_R
25f40 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23 OW 0x04.#
25f50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 define SQLITE_TR
25f60 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 ACE_CLOSE 0
25f70 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 x08../*.** CAPI3
25f80 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48 REF: SQL Trace H
25f90 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ook.** METHOD: s
25fa0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
25fb0 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f e sqlite3_trace_
25fc0 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 v2(D,M,X,P) inte
25fd0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 rface registers
25fe0 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b a trace callback
25ff0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 .** function X a
26000 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65 gainst [database
26010 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 connection] D,
26020 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d using property m
26030 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e ask M.** and con
26040 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 text pointer P.
26050 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62 ^If the X callb
26060 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f ack is.** NULL o
26070 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 r if the M mask
26080 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 is zero, then tr
26090 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 acing is disable
260a0 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 d. The.** M arg
260b0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 ument should be
260c0 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65 the bitwise OR-e
260d0 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 d combination of
260e0 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 .** zero or more
260f0 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 [SQLITE_TRACE]
26100 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a constants..**.**
26110 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 ^Each call to e
26120 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72 ither sqlite3_tr
26130 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ace() or sqlite3
26140 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72 _trace_v2() over
26150 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 rides .** (cance
26160 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61 ls) any prior ca
26170 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 lls to sqlite3_t
26180 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 race() or sqlite
26190 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 3_trace_v2()..**
261a0 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 .** ^The X callb
261b0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
261c0 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74 henever any of t
261d0 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 he events identi
261e0 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b fied by .** mask
261f0 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 M occur. ^The
26200 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76 integer return v
26210 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61 alue from the ca
26220 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e llback is curren
26230 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 tly.** ignored,
26240 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20 though this may
26250 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 change in future
26260 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c releases. Call
26270 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e back.** implemen
26280 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 tations should r
26290 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e eturn zero to en
262a0 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70 sure future comp
262b0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a atibility..**.**
262c0 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 ^A trace callba
262d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 ck is invoked wi
262e0 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 th four argument
262f0 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c s: callback(T,C,
26300 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 P,X)..** ^The T
26310 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 argument is one
26320 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 of the [SQLITE_T
26330 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e RACE].** constan
26340 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 ts to indicate w
26350 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 hy the callback
26360 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 was invoked..**
26370 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 ^The C argument
26380 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
26390 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 context pointer
263a0 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 ..** The P and X
263b0 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 arguments are p
263c0 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 ointers whose me
263d0 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e anings depend on
263e0 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 T..**.** The sq
263f0 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 lite3_trace_v2()
26400 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e interface is in
26410 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63 tended to replac
26420 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 e the legacy.**
26430 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 interfaces [sqli
26440 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 te3_trace()] and
26450 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c [sqlite3_profil
26460 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 e()], both of wh
26470 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 ich.** are depre
26480 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 cated..*/.int sq
26490 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a lite3_trace_v2(.
264a0 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e sqlite3*,. un
264b0 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 signed uMask,.
264c0 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 int(*xCallback)(
264d0 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 unsigned,void*,v
264e0 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 oid*,void*),. v
264f0 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a oid *pCtx.);../*
26500 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 .** CAPI3REF: Qu
26510 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c ery Progress Cal
26520 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 lbacks.** METHOD
26530 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
26540 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f ^The sqlite3_pro
26550 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c gress_handler(D,
26560 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 N,X,P) interface
26570 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c causes the call
26580 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e back.** function
26590 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 X to be invoked
265a0 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 periodically du
265b0 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e ring long runnin
265c0 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 g calls to.** [s
265d0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 qlite3_exec()],
265e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
265f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 and [sqlite3_ge
26600 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a t_table()] for.*
26610 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
26620 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 ction D. An exa
26630 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 mple use for thi
26640 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 s.** interface i
26650 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 s to keep a GUI
26660 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 updated during a
26670 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a large query..**
26680 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 .** ^The paramet
26690 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 er P is passed t
266a0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e hrough as the on
266b0 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ly parameter to
266c0 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b the .** callback
266d0 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 function X. ^T
266e0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 he parameter N i
266f0 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 s the approximat
26700 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 e number of .**
26710 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 [virtual machine
26720 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 instructions] t
26730 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 hat are evaluate
26740 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 d between succes
26750 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 sive.** invocati
26760 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 ons of the callb
26770 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 ack X. ^If N is
26780 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 less than one t
26790 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 hen the progress
267a0 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 .** handler is d
267b0 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e isabled..**.** ^
267c0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 Only a single pr
267d0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d ogress handler m
267e0 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 ay be defined at
267f0 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a one time per.**
26800 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
26810 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 ction]; setting
26820 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 a new progress h
26830 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 andler cancels t
26840 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 he.** old one.
26850 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 ^Setting paramet
26860 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 er X to NULL dis
26870 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 ables the progre
26880 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e ss handler..** ^
26890 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e The progress han
268a0 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 dler is also dis
268b0 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 abled by setting
268c0 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 N to a value le
268d0 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a ss.** than 1..**
268e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 .** ^If the prog
268f0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 ress callback re
26900 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
26910 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 the operation is
26920 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e .** interrupted.
26930 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 This feature c
26940 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d an be used to im
26950 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 plement a.** "Ca
26960 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 ncel" button on
26970 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 a GUI progress d
26980 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a ialog box..**.**
26990 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 The progress ha
269a0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d ndler callback m
269b0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 ust not do anyth
269c0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f ing that will mo
269d0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 dify.** the data
269e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
269f0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
26a00 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
26a10 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 r..** Note that
26a20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
26a30 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 _v2()] and [sqli
26a40 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 te3_step()] both
26a50 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a modify their.**
26a60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
26a70 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 tions for the me
26a80 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 aning of "modify
26a90 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 " in this paragr
26aa0 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 aph..**.*/.void
26ab0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 sqlite3_progress
26ac0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
26ad0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 *, int, int(*)(v
26ae0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a oid*), void*);..
26af0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
26b00 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 Opening A New Da
26b10 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
26b20 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 n.** CONSTRUCTOR
26b30 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
26b40 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
26b50 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 open an SQLite d
26b60 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 atabase file as
26b70 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
26b80 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 .** filename ar
26b90 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c gument. ^The fil
26ba0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 ename argument i
26bb0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
26bc0 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 UTF-8 for.** sq
26bd0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 lite3_open() and
26be0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
26bf0 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 () and as UTF-16
26c00 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 in the native b
26c10 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 yte.** order for
26c20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
26c30 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 ). ^(A [database
26c40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e connection] han
26c50 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a dle is usually.*
26c60 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 * returned in *p
26c70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 pDb, even if an
26c80 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 error occurs. T
26c90 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f he only exceptio
26ca0 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 n is that.** if
26cb0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 SQLite is unable
26cc0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d to allocate mem
26cd0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 ory to hold the
26ce0 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
26cf0 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c ,.** a NULL will
26d00 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f be written into
26d10 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f *ppDb instead o
26d20 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 f a pointer to t
26d30 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 he [sqlite3].**
26d40 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 object.)^ ^(If t
26d50 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
26d60 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 pened (and/or cr
26d70 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 eated) successfu
26d80 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 lly, then.** [SQ
26d90 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 LITE_OK] is retu
26da0 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 rned. Otherwise
26db0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
26dc0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 is returned.)^
26dd0 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ^The.** [sqlite3
26de0 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 _errmsg()] or [s
26df0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
26e00 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 )] routines can
26e10 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 be used to obtai
26e20 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 n.** an English
26e30 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 language descrip
26e40 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f tion of the erro
26e50 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 r following a fa
26e60 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 ilure of any.**
26e70 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f of the sqlite3_o
26e80 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a pen() routines..
26e90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 **.** ^The defau
26ea0 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c lt encoding will
26eb0 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 be UTF-8 for da
26ec0 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20 tabases created
26ed0 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 using.** sqlite3
26ee0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 _open() or sqlit
26ef0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e e3_open_v2(). ^
26f00 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f The default enco
26f10 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 ding for databas
26f20 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 es.** created us
26f30 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ing sqlite3_open
26f40 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 16() will be UTF
26f50 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 -16 in the nativ
26f60 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a e byte order..**
26f70 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e .** Whether or n
26f80 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 ot an error occu
26f90 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 rs when it is op
26fa0 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a ened, resources.
26fb0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
26fc0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 th the [database
26fd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e connection] han
26fe0 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 dle should be re
26ff0 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 leased by.** pas
27000 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 sing it to [sqli
27010 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 te3_close()] whe
27020 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 n it is no longe
27030 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a r required..**.*
27040 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 * The sqlite3_op
27050 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 en_v2() interfac
27060 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c e works like sql
27070 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 ite3_open().** e
27080 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 xcept that it ac
27090 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 cepts two additi
270a0 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 onal parameters
270b0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 for additional c
270c0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 ontrol.** over t
270d0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 he new database
270e0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 connection. ^(T
270f0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 he flags paramet
27100 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 er to.** sqlite3
27110 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 _open_v2() can t
27120 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 ake one of.** th
27130 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 e following thre
27140 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e e values, option
27150 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 ally combined wi
27160 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 th the .** [SQLI
27170 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d TE_OPEN_NOMUTEX]
27180 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 , [SQLITE_OPEN_F
27190 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 ULLMUTEX], [SQLI
271a0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
271b0 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 CHE],.** [SQLITE
271c0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 _OPEN_PRIVATECAC
271d0 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c HE], and/or [SQL
271e0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c ITE_OPEN_URI] fl
271f0 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c ags:)^.**.** <dl
27200 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 >.** ^(<dt>[SQLI
27210 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
27220 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 ]</dt>.** <dd>Th
27230 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
27240 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c ened in read-onl
27250 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 y mode. If the
27260 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f database does no
27270 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 t.** already exi
27280 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 st, an error is
27290 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e returned.</dd>)^
272a0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 .**.** ^(<dt>[SQ
272b0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
272c0 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ITE]</dt>.** <dd
272d0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 >The database is
272e0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 opened for read
272f0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 ing and writing
27300 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 if possible, or
27310 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 reading.** only
27320 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 if the file is w
27330 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 rite protected b
27340 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 y the operating
27350 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 system. In eith
27360 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 er.** case the d
27370 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 atabase must alr
27380 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 eady exist, othe
27390 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 rwise an error i
273a0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e s returned.</dd>
273b0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b )^.**.** ^(<dt>[
273c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
273d0 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 WRITE] | [SQLITE
273e0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 _OPEN_CREATE]</d
273f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 t>.** <dd>The da
27400 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
27410 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 for reading and
27420 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 writing, and is
27430 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 created if.** i
27440 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 t does not alrea
27450 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 dy exist. This i
27460 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 s the behavior t
27470 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 hat is always us
27480 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 ed for.** sqlite
27490 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 3_open() and sql
274a0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f ite3_open16().</
274b0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a dd>)^.** </dl>.*
274c0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 *.** If the 3rd
274d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
274e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
274f0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 s not one of the
27500 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 .** combinations
27510 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 shown above opt
27520 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 ionally combined
27530 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b with other.** [
27540 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
27550 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 ONLY | SQLITE_OP
27560 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 EN_* bits].** th
27570 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
27580 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
27590 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c .** ^If the [SQL
275a0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
275b0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 ] flag is set, t
275c0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
275d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f connection.** o
275e0 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 pens in the mult
275f0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 i-thread [thread
27600 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e ing mode] as lon
27610 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d g as the single-
27620 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 thread.** mode h
27630 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 as not been set
27640 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 at compile-time
27650 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 or start-time.
27660 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ^If the.** [SQLI
27670 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 TE_OPEN_FULLMUTE
27680 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 X] flag is set t
27690 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
276a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e connection open
276b0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 s.** in the seri
276c0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
276d0 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 g mode] unless s
276e0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 ingle-thread was
276f0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 .** previously s
27700 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 elected at compi
27710 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 le-time or start
27720 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b -time..** ^The [
27730 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
27740 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 EDCACHE] flag ca
27750 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 uses the databas
27760 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 e connection to
27770 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 be.** eligible t
27780 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 o use [shared ca
27790 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 che mode], regar
277a0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 dless of whether
277b0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a or not shared.*
277c0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c * cache is enabl
277d0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
277e0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 3_enable_shared_
277f0 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a cache()]. ^The.
27800 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
27810 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c PRIVATECACHE] fl
27820 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 ag causes the da
27830 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
27840 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 n to not.** part
27850 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 icipate in [shar
27860 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 ed cache mode] e
27870 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 ven if it is ena
27880 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 bled..**.** ^The
27890 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
278a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
278b0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 n_v2() is the na
278c0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 me of the.** [sq
278d0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
278e0 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 t that defines t
278f0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
27900 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 tem interface th
27910 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 at.** the new da
27920 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
27930 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e n should use. ^
27940 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
27950 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 rameter is.** a
27960 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
27970 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 n the default [s
27980 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
27990 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a ct is used..**.*
279a0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 * ^If the filena
279b0 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 me is ":memory:"
279c0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 , then a private
279d0 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d , temporary in-m
279e0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a emory database.*
279f0 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 * is created for
27a00 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e the connection.
27a10 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 ^This in-memor
27a20 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 y database will
27a30 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 vanish when.** t
27a40 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
27a50 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 ection is closed
27a60 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
27a70 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 ns of SQLite mig
27a80 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f ht.** make use o
27a90 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 f additional spe
27aa0 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 cial filenames t
27ab0 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 hat begin with t
27ac0 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 he ":" character
27ad0 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d ..** It is recom
27ae0 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e mended that when
27af0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
27b00 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f name actually do
27b10 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a es begin with.**
27b20 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 a ":" character
27b30 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 you should pref
27b40 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 ix the filename
27b50 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 with a pathname
27b60 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 such as.** "./"
27b70 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 to avoid ambigui
27b80 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ty..**.** ^If th
27b90 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e e filename is an
27ba0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 empty string, t
27bb0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 hen a private, t
27bc0 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 emporary.** on-d
27bd0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c isk database wil
27be0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e l be created. ^
27bf0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 This private dat
27c00 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a abase will be.**
27c10 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 automatically d
27c20 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 eleted as soon a
27c30 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 s the database c
27c40 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f onnection is clo
27c50 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 sed..**.** [[URI
27c60 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 filenames in sq
27c70 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c lite3_open()]] <
27c80 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 h3>URI Filenames
27c90 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 </h3>.**.** ^If
27ca0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 [URI filename] i
27cb0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 nterpretation is
27cc0 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 enabled, and th
27cd0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d e filename argum
27ce0 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 ent.** begins wi
27cf0 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e th "file:", then
27d00 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 the filename is
27d10 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
27d20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 a URI. ^URI.** f
27d30 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 ilename interpre
27d40 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 tation is enable
27d50 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 d if the [SQLITE
27d60 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 _OPEN_URI] flag
27d70 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 is.** set in the
27d80 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
27d90 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
27da0 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 v2(), or if it h
27db0 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c as.** been enabl
27dc0 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e ed globally usin
27dd0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f g the [SQLITE_CO
27de0 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e NFIG_URI] option
27df0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 with the.** [sq
27e00 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
27e10 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 method or by the
27e20 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 [SQLITE_USE_URI
27e30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
27e40 70 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69 ption..** URI fi
27e50 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 lename interpret
27e60 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 ation is turned
27e70 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c off.** by defaul
27e80 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 t, but future re
27e90 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
27ea0 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 might enable UR
27eb0 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e I filename.** in
27ec0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 terpretation by
27ed0 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b default. See "[
27ee0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 URI filenames]"
27ef0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
27f00 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
27f10 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d *.** URI filenam
27f20 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 es are parsed ac
27f30 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 cording to RFC 3
27f40 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 986. ^If the URI
27f50 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 contains an.**
27f60 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 authority, then
27f70 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 it must be eithe
27f80 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e r an empty strin
27f90 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 g or the string
27fa0 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e .** "localhost".
27fb0 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 ^If the authori
27fc0 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 ty is not an emp
27fd0 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f ty string or "lo
27fe0 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a calhost", an .**
27ff0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
28000 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 ed to the caller
28010 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 . ^The fragment
28020 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 component of a U
28030 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 RI, if .** prese
28040 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a nt, is ignored..
28050 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 **.** ^SQLite us
28060 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 es the path comp
28070 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 onent of the URI
28080 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 as the name of
28090 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a the disk file.**
280a0 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 which contains
280b0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 the database. ^I
280c0 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e f the path begin
280d0 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 s with a '/' cha
280e0 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e racter, .** then
280f0 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 it is interpret
28100 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 ed as an absolut
28110 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 e path. ^If the
28120 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 path does not be
28130 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 gin .** with a '
28140 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 /' (meaning that
28150 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 the authority s
28160 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 ection is omitte
28170 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a d from the URI).
28180 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 ** then the path
28190 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
281a0 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 as a relative pa
281b0 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e th. .** ^(On win
281c0 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 dows, the first
281d0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 component of an
281e0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a absolute path .*
281f0 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 * is a drive spe
28200 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e cification (e.g.
28210 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 "C:").)^.**.**
28220 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 [[core URI query
28230 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a parameters]].**
28240 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f The query compo
28250 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 nent of a URI ma
28260 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 y contain parame
28270 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e ters that are in
28280 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 terpreted.** eit
28290 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 her by SQLite it
282a0 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 self, or by a [V
282b0 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 FS | custom VFS
282c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e implementation].
282d0 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 .** SQLite and i
282e0 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 ts built-in [VFS
282f0 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 es] interpret th
28300 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 e.** following q
28310 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a uery parameters:
28320 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 .**.** <ul>.**
28330 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e <li> <b>vfs</b>
28340 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 : ^The "vfs" par
28350 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 ameter may be us
28360 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 ed to specify th
28370 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 e name of.**
28380 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 a VFS object th
28390 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 at provides the
283a0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
283b0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 interface that
283c0 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 should.** be
283d0 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 used to access
283e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
283f0 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 e on disk. ^If t
28400 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 his option is se
28410 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 t to.** an e
28420 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 mpty string the
28430 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 default VFS obje
28440 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 ct is used. ^Spe
28450 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f cifying an unkno
28460 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 wn.** VFS is
28470 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 an error. ^If s
28480 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
28490 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 is used and the
284a0 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a vfs option is.*
284b0 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 * present, t
284c0 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 hen the VFS spec
284d0 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 ified by the opt
284e0 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 ion takes preced
284f0 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 ence over.**
28500 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 the value passe
28510 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 d as the fourth
28520 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
28530 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a ite3_open_v2()..
28540 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e **.** <li> <b>
28550 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 mode</b>: ^(The
28560 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d mode parameter m
28570 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 ay be set to eit
28580 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a her "ro", "rw",.
28590 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 ** "rwc", or
285a0 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d "memory". Attem
285b0 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 pting to set it
285c0 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c to any other val
285d0 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 ue is.** an
285e0 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 error)^. .**
285f0 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 ^If "ro" is spe
28600 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 cified, then the
28610 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
28620 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c ned for read-onl
28630 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 y .** access
28640 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 , just as if the
28650 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
28660 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 ADONLY] flag had
28670 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 been set in the
28680 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 .** third a
28690 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
286a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 e3_open_v2(). ^I
286b0 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f f the mode optio
286c0 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 n is set to .**
286d0 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 "rw", then t
286e0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
286f0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 pened for read-w
28700 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 rite (but not cr
28710 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 eate) .** ac
28720 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 cess, as if SQLI
28730 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
28740 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 E (but not SQLIT
28750 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 E_OPEN_CREATE) h
28760 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 ad .** been
28770 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 set. ^Value "rwc
28780 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 " is equivalent
28790 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 to setting both
287a0 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f .** SQLITE_O
287b0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e PEN_READWRITE an
287c0 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 d SQLITE_OPEN_CR
287d0 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d EATE. ^If the m
287e0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a ode option is.**
287f0 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d set to "mem
28800 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 ory" then a pure
28810 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 [in-memory data
28820 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 base] that never
28830 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 reads.** or
28840 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 writes from dis
28850 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 k is used. ^It i
28860 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 s an error to sp
28870 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f ecify a value fo
28880 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 r.** the mod
28890 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 e parameter that
288a0 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 is less restric
288b0 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 tive than that s
288c0 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 pecified by.**
288d0 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 the flags pas
288e0 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 sed in the third
288f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
28900 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
28910 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 .**.** <li> <b
28920 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 >cache</b>: ^The
28930 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 cache parameter
28940 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 may be set to e
28950 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f ither "shared" o
28960 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 r.** "privat
28970 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 e". ^Setting it
28980 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 to "shared" is e
28990 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 quivalent to set
289a0 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 ting the.**
289b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
289c0 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 EDCACHE bit in t
289d0 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
289e0 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 t passed to.**
289f0 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f sqlite3_open_
28a00 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 v2(). ^Setting t
28a10 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 he cache paramet
28a20 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 er to "private"
28a30 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 is .** equiv
28a40 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 alent to setting
28a50 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e the SQLITE_OPEN
28a60 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 _PRIVATECACHE bi
28a70 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 t..** ^If sq
28a80 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
28a90 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 is used and the
28aa0 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 "cache" paramete
28ab0 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a r is present in.
28ac0 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c ** a URI fil
28ad0 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 ename, its value
28ae0 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 overrides any b
28af0 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 ehavior requeste
28b00 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 d by setting.**
28b10 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f SQLITE_OPEN_
28b20 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 PRIVATECACHE or
28b30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
28b40 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a EDCACHE flag..**
28b50 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f .** <li> <b>pso
28b60 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 w</b>: ^The psow
28b70 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 parameter indic
28b80 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 ates whether or
28b90 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b not the.** [
28ba0 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 powersafe overwr
28bb0 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f ite] property do
28bc0 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 es or does not a
28bd0 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 pply to the.**
28be0 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 storage media
28bf0 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 on which the da
28c00 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 tabase file resi
28c10 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e des..**.** <li>
28c20 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 <b>nolock</b>:
28c30 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 ^The nolock para
28c40 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 meter is a boole
28c50 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 an query paramet
28c60 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 er.** which
28c70 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 if set disables
28c80 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 file locking in
28c90 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c rollback journal
28ca0 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a modes. This.**
28cb0 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 is useful f
28cc0 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 or accessing a d
28cd0 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c atabase on a fil
28ce0 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 esystem that doe
28cf0 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 s not.** sup
28d00 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 port locking. C
28d10 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 aution: Databas
28d20 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 e corruption mig
28d30 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f ht result if two
28d40 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 .** or more
28d50 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 processes write
28d60 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 to the same data
28d70 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 base and any one
28d80 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 of those.**
28d90 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 processes uses
28da0 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 nolock=1..**.**
28db0 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 <li> <b>immutab
28dc0 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d le</b>: ^The imm
28dd0 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 utable parameter
28de0 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 is a boolean qu
28df0 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d ery.** param
28e00 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 eter that indica
28e10 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 tes that the dat
28e20 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 abase file is st
28e30 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 ored on.** r
28e40 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 ead-only media.
28e50 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 ^When immutable
28e60 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 is set, SQLite
28e70 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 assumes that the
28e80 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 .** database
28e90 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 file cannot be
28ea0 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 changed, even by
28eb0 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 a process with
28ec0 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 higher.** pr
28ed0 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 ivilege, and so
28ee0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
28ef0 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 opened read-only
28f00 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 and all locking
28f10 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e .** and chan
28f20 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 ge detection is
28f30 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 disabled. Cauti
28f40 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 on: Setting the
28f50 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 immutable.**
28f60 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 property on a d
28f70 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 atabase file tha
28f80 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 t does in fact c
28f90 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 hange can result
28fa0 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 .** in incor
28fb0 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c rect query resul
28fc0 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 ts and/or [SQLIT
28fd0 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 E_CORRUPT] error
28fe0 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c s..** See al
28ff0 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 so: [SQLITE_IOCA
29000 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a P_IMMUTABLE]..**
29010 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e .** </ul>
29020 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 .**.** ^Specifyi
29030 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 ng an unknown pa
29040 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 rameter in the q
29050 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f uery component o
29060 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 f a URI is not a
29070 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 n.** error. Fut
29080 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
29090 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 SQLite might und
290a0 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e erstand addition
290b0 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 al query.** para
290c0 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 meters. See "[q
290d0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 uery parameters
290e0 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 with special mea
290f0 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 ning to SQLite]"
29100 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e for.** addition
29110 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
29120 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 **.** [[URI file
29130 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 name examples]]
29140 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 <h3>URI filename
29150 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a examples</h3>.*
29160 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 *.** <table bord
29170 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e er="1" align=cen
29180 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d ter cellpadding=
29190 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 5>.** <tr><th> U
291a0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 RI filenames <th
291b0 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 > Results.** <tr
291c0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e ><td> file:data.
291d0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 db <td> .**
291e0 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 Open the fi
291f0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 le "data.db" in
29200 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 the current dire
29210 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 ctory..** <tr><t
29220 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 d> file:/home/fr
29230 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a ed/data.db<br>.*
29240 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a * file:
29250 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 ///home/fred/dat
29260 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 a.db <br> .**
29270 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f file://lo
29280 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 calhost/home/fre
29290 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c d/data.db <br> <
292a0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 td> .**
292b0 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 Open the databa
292c0 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 se file "/home/f
292d0 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a red/data.db"..**
292e0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f <tr><td> file:/
292f0 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 /darkstar/home/f
29300 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e red/data.db <td>
29310 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e .** An
29320 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 error. "darksta
29330 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f r" is not a reco
29340 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 gnized authority
29350 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 ..** <tr><td sty
29360 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a le="white-space:
29370 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 nowrap"> .**
29380 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a file:///C:
29390 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 /Documents%20and
293a0 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 %20Settings/fred
293b0 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 /Desktop/data.db
293c0 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e .** <td> Win
293d0 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 dows only: Open
293e0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 the file "data.d
293f0 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 b" on fred's des
29400 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a ktop on drive.**
29410 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f C:. No
29420 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 te that the %20
29430 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 escaping in this
29440 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 example is not
29450 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 strictly .**
29460 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 necessary
29470 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 - space characte
29480 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c rs can be used l
29490 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 iterally.**
294a0 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 in URI file
294b0 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 names..** <tr><t
294c0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f d> file:data.db?
294d0 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 mode=ro&cache=pr
294e0 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 ivate <td> .**
294f0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c Open fil
29500 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 e "data.db" in t
29510 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 he current direc
29520 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e tory for read-on
29530 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 ly access..**
29540 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 Regardles
29550 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
29560 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 not shared-cache
29570 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 mode is enabled
29580 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 by.**
29590 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 default, use a p
295a0 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a rivate cache..**
295b0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f <tr><td> file:/
295c0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
295d0 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 b?vfs=unix-dotfi
295e0 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 le <td>.**
295f0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f Open file "/
29600 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
29610 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 b". Use the spec
29620 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f ial VFS "unix-do
29630 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 tfile".**
29640 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 that uses dot
29650 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 -files in place
29660 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 of posix advisor
29670 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 y locking..** <t
29680 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 r><td> file:data
29690 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c .db?mode=readonl
296a0 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 y <td> .**
296b0 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 An error. "r
296c0 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 eadonly" is not
296d0 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 a valid option f
296e0 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 or the "mode" pa
296f0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 rameter..** </ta
29700 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 ble>.**.** ^URI
29710 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 hexadecimal esca
29720 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 pe sequences (%H
29730 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 H) are supported
29740 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 within the path
29750 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f and.** query co
29760 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 mponents of a UR
29770 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c I. A hexadecimal
29780 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 escape sequence
29790 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a consists of a.*
297a0 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d * percent sign -
297b0 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 "%" - followed
297c0 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 by exactly two h
297d0 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 exadecimal digit
297e0 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 s .** specifying
297f0 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e an octet value.
29800 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 ^Before the pat
29810 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f h or query compo
29820 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 nents of a.** UR
29830 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 I filename are i
29840 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 nterpreted, they
29850 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 are encoded usi
29860 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c ng UTF-8 and all
29870 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c .** hexadecimal
29880 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 escape sequence
29890 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 s replaced by a
298a0 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 single byte cont
298b0 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f aining the.** co
298c0 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 rresponding octe
298d0 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 t. If this proce
298e0 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 ss generates an
298f0 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e invalid UTF-8 en
29900 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 coding,.** the r
29910 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 esults are undef
29920 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e ined..**.** <b>N
29930 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 ote to Windows u
29940 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 sers:</b> The e
29950 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 ncoding used for
29960 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 the filename ar
29970 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c gument.** of sql
29980 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
29990 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
299a0 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c ) must be UTF-8,
299b0 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a not whatever.**
299c0 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 codepage is cur
299d0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 rently defined.
299e0 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 Filenames conta
299f0 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f ining internatio
29a00 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 nal.** character
29a10 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 s must be conver
29a20 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 ted to UTF-8 pri
29a30 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 or to passing th
29a40 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 em into.** sqlit
29a50 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c e3_open() or sql
29a60 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a ite3_open_v2()..
29a70 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f **.** <b>Note to
29a80 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 Windows Runtime
29a90 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 users:</b> The
29aa0 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 temporary direc
29ab0 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 tory must be set
29ac0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c .** prior to cal
29ad0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 ling sqlite3_ope
29ae0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f n() or sqlite3_o
29af0 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 pen_v2(). Other
29b00 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a wise, various.**
29b10 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 features that r
29b20 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f equire the use o
29b30 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 f temporary file
29b40 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a s may fail..**.*
29b50 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
29b60 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 ite3_temp_direct
29b70 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ory].*/.int sqli
29b80 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 te3_open(. cons
29b90 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
29ba0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
29bb0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
29bc0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
29bd0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a ppDb /*
29be0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
29bf0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 handle */.);.int
29c00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
29c10 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 . const void *f
29c20 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 ilename, /* Da
29c30 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
29c40 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 (UTF-16) */. sq
29c50 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 lite3 **ppDb
29c60 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 /* OUT: SQ
29c70 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a Lite db handle *
29c80 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 /.);.int sqlite3
29c90 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 _open_v2(. cons
29ca0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
29cb0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
29cc0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
29cd0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
29ce0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a ppDb, /*
29cf0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
29d00 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 handle */. int
29d10 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 flags,
29d20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a /* Flags */.
29d30 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 const char *zV
29d40 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d fs /* Nam
29d50 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 e of VFS module
29d60 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a to use */.);../*
29d70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
29d80 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 tain Values For
29d90 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a URI Parameters.*
29da0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 *.** These are u
29db0 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c tility routines,
29dc0 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 useful to VFS i
29dd0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 mplementations,
29de0 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f that check.** to
29df0 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 see if a databa
29e00 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 se file was a UR
29e10 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 I that contained
29e20 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 a specific quer
29e30 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c y .** parameter,
29e40 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 and if so obtai
29e50 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 ns the value of
29e60 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d that query param
29e70 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 eter..**.** If F
29e80 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 is the database
29e90 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 filename pointe
29ea0 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 r passed into th
29eb0 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 e xOpen() method
29ec0 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d of .** a VFS im
29ed0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 plementation whe
29ee0 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 n the flags para
29ef0 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 meter to xOpen()
29f00 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 has one or .**
29f10 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c more of the [SQL
29f20 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 ITE_OPEN_URI] or
29f30 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
29f40 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 IN_DB] bits set
29f50 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 and.** P is the
29f60 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 name of the quer
29f70 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 y parameter, the
29f80 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 n.** sqlite3_uri
29f90 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 _parameter(F,P)
29fa0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 returns the valu
29fb0 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 e of the P.** pa
29fc0 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 rameter if it ex
29fd0 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 ists or a NULL p
29fe0 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 ointer if P does
29ff0 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 not appear as a
2a000 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d .** query param
2a010 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 eter on F. If P
2a020 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 is a query para
2a030 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 meter of F.** ha
2a040 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 s no explicit va
2a050 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 lue, then sqlite
2a060 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 3_uri_parameter(
2a070 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 F,P) returns.**
2a080 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
2a090 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a empty string..**
2a0a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
2a0b0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
2a0c0 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d B) routine assum
2a0d0 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 es that P is a b
2a0e0 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 oolean.** parame
2a0f0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ter and returns
2a100 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 true (1) or fals
2a110 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 e (0) according
2a120 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 to the value.**
2a130 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 of P. The sqlit
2a140 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
2a150 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 ,P,B) routine re
2a160 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 turns true (1) i
2a170 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f f the.** value o
2a180 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 f query paramete
2a190 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 r P is one of "y
2a1a0 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 es", "true", or
2a1b0 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 "on" in any.** c
2a1c0 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 ase or if the va
2a1d0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 lue begins with
2a1e0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 a non-zero numbe
2a1f0 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 r. The .** sqli
2a200 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
2a210 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 F,P,B) routines
2a220 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 returns false (0
2a230 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f ) if the value o
2a240 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d f.** query param
2a250 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 eter P is one of
2a260 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 "no", "false",
2a270 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 or "off" in any
2a280 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 case or.** if th
2a290 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 e value begins w
2a2a0 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 ith a numeric ze
2a2b0 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 ro. If P is not
2a2c0 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 a query.** para
2a2d0 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 meter on F or if
2a2e0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
2a2f0 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 is does not matc
2a300 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 h any of the.**
2a310 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 above, then sqli
2a320 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
2a330 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 F,P,B) returns (
2a340 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 B!=0)..**.** The
2a350 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 sqlite3_uri_int
2a360 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 64(F,P,D) routin
2a370 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 e converts the v
2a380 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 alue of P into a
2a390 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 .** 64-bit signe
2a3a0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 d integer and re
2a3b0 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 turns that integ
2a3c0 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f er, or D if P do
2a3d0 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e es not.** exist.
2a3e0 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f If the value o
2a3f0 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 f P is something
2a400 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 other than an i
2a410 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 nteger, then.**
2a420 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 zero is returned
2a430 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 ..** .** If F is
2a440 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
2a450 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 then sqlite3_ur
2a460 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 i_parameter(F,P)
2a470 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e returns NULL an
2a480 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 d.** sqlite3_uri
2a490 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
2a4a0 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 returns B. If F
2a4b0 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 is not a NULL p
2a4c0 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 ointer and.** is
2a4d0 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 not a database
2a4e0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f file pathname po
2a4f0 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 inter that SQLit
2a500 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 e passed into th
2a510 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d e xOpen.** VFS m
2a520 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 ethod, then the
2a530 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 behavior of this
2a540 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 routine is unde
2a550 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
2a560 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c ly.** undesirabl
2a570 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 e..**.** See the
2a580 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 [URI filename]
2a590 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f documentation fo
2a5a0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 r additional inf
2a5b0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 6f 6e ormation..*/.con
2a5c0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
2a5d0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 _uri_parameter(c
2a5e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
2a5f0 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 name, const char
2a600 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 *zParam);.int s
2a610 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 qlite3_uri_boole
2a620 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a an(const char *z
2a630 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 File, const char
2a640 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 *zParam, int bD
2a650 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 efault);.sqlite3
2a660 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 _int64 sqlite3_u
2a670 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 ri_int64(const c
2a680 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 har*, const char
2a690 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
2a6a0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 );.../*.** CAPI3
2a6b0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 REF: Error Codes
2a6c0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a And Messages.**
2a6d0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
2a6e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d .**.** ^If the m
2a6f0 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 ost recent sqlit
2a700 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 e3_* API call as
2a710 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a sociated with .*
2a720 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
2a730 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 ection] D failed
2a740 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 , then the sqlit
2a750 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e e3_errcode(D) in
2a760 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 terface.** retur
2a770 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b ns the numeric [
2a780 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 result code] or
2a790 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
2a7a0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a code] for that.
2a7b0 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 ** API call..**
2a7c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 ^The sqlite3_ext
2a7d0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a ended_errcode().
2a7e0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
2a7f0 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 the same except
2a800 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 that it always r
2a810 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b eturns the .** [
2a820 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
2a830 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 code] even when
2a840 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
2a850 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 codes are.** dis
2a860 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 abled..**.** The
2a870 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 values returned
2a880 20 62 79 20 73 71 6c 69 74 65 33 5f 65 72 72 63 by sqlite3_errc
2a890 6f 64 65 28 29 20 61 6e 64 2f 6f 72 0a 2a 2a 20 ode() and/or.**
2a8a0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
2a8b0 5f 65 72 72 63 6f 64 65 28 29 20 6d 69 67 68 74 _errcode() might
2a8c0 20 63 68 61 6e 67 65 20 77 69 74 68 20 65 61 63 change with eac
2a8d0 68 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 45 h API call..** E
2a8e0 78 63 65 70 74 2c 20 74 68 65 72 65 20 61 72 65 xcept, there are
2a8f0 20 73 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 some interfaces
2a900 20 74 68 61 74 20 61 72 65 20 67 75 61 72 61 6e that are guaran
2a910 74 65 65 64 20 74 6f 20 6e 65 76 65 72 0a 2a 2a teed to never.**
2a920 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 change the valu
2a930 65 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 63 e of the error c
2a940 6f 64 65 2e 20 20 54 68 65 20 65 72 72 6f 72 2d ode. The error-
2a950 63 6f 64 65 20 70 72 65 73 65 72 76 69 6e 67 0a code preserving.
2a960 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 ** interfaces ar
2a970 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a e:.**.** <ul>.**
2a980 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 <li> sqlite3_er
2a990 72 63 6f 64 65 28 29 0a 2a 2a 20 3c 6c 69 3e 20 rcode().** <li>
2a9a0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
2a9b0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 3c 6c _errcode().** <l
2a9c0 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 i> sqlite3_errms
2a9d0 67 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 g().** <li> sqli
2a9e0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 0a 2a te3_errmsg16().*
2a9f0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 54 * </ul>.**.** ^T
2aa00 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 he sqlite3_errms
2aa10 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f g() and sqlite3_
2aa20 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 errmsg16() retur
2aa30 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 n English-langua
2aa40 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 ge.** text that
2aa50 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 describes the er
2aa60 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 ror, as either U
2aa70 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 TF-8 or UTF-16 r
2aa80 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
2aa90 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 ^(Memory to hold
2aaa0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
2aab0 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e ge string is man
2aac0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e aged internally.
2aad0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
2aae0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 ion does not nee
2aaf0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 d to worry about
2ab00 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 freeing the res
2ab10 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c ult..** However,
2ab20 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e the error strin
2ab30 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 g might be overw
2ab40 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f ritten or deallo
2ab50 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 cated by.** subs
2ab60 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
2ab70 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
2ab80 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 erface functions
2ab90 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 .)^.**.** ^The s
2aba0 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 qlite3_errstr()
2abb0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2abc0 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 s the English-la
2abd0 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 nguage text.** t
2abe0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 hat describes th
2abf0 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c e [result code],
2ac00 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 as UTF-8..** ^(
2ac10 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 Memory to hold t
2ac20 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
2ac30 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 string is manag
2ac40 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a ed internally.**
2ac50 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 and must not be
2ac60 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 freed by the ap
2ac70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a plication)^..**.
2ac80 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 ** When the seri
2ac90 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
2aca0 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 g mode] is in us
2acb0 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 e, it might be t
2acc0 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 he.** case that
2acd0 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f a second error o
2ace0 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 ccurs on a separ
2acf0 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 ate thread in be
2ad00 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d tween.** the tim
2ad10 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 e of the first e
2ad20 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c rror and the cal
2ad30 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 l to these inter
2ad40 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 faces..** When t
2ad50 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 hat happens, the
2ad60 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 second error wi
2ad70 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 ll be reported s
2ad80 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e ince these.** in
2ad90 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 terfaces always
2ada0 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 report the most
2adb0 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 recent result.
2adc0 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 To avoid.** this
2add0 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 , each thread ca
2ade0 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 n obtain exclusi
2adf0 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 ve use of the [d
2ae00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2ae10 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f on] D.** by invo
2ae20 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 king [sqlite3_mu
2ae30 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 tex_enter]([sqli
2ae40 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 te3_db_mutex](D)
2ae50 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 ) before beginni
2ae60 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 ng.** to use D a
2ae70 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c nd invoking [sql
2ae80 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 ite3_mutex_leave
2ae90 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 ]([sqlite3_db_mu
2aea0 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a tex](D)) after.*
2aeb0 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 * all calls to t
2aec0 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 he interfaces li
2aed0 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f sted here are co
2aee0 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 mpleted..**.** I
2aef0 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 f an interface f
2af00 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 ails with SQLITE
2af10 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 _MISUSE, that me
2af20 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 ans the interfac
2af30 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 e.** was invoked
2af40 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 incorrectly by
2af50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e the application.
2af60 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 In that case,
2af70 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 the.** error cod
2af80 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 e and message ma
2af90 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 y or may not be
2afa0 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 set..*/.int sqli
2afb0 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 te3_errcode(sqli
2afc0 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 te3 *db);.int sq
2afd0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 lite3_extended_e
2afe0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a rrcode(sqlite3 *
2aff0 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 db);.const char
2b000 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 *sqlite3_errmsg(
2b010 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 sqlite3*);.const
2b020 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 void *sqlite3_e
2b030 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a rrmsg16(sqlite3*
2b040 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
2b050 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e qlite3_errstr(in
2b060 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2b070 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 REF: Prepared St
2b080 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a atement Object.*
2b090 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 * KEYWORDS: {pre
2b0a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d pared statement}
2b0b0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
2b0c0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 ments}.**.** An
2b0d0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
2b0e0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e object represen
2b0f0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 ts a single SQL
2b100 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a statement that.*
2b110 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 * has been compi
2b120 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 led into binary
2b130 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 form and is read
2b140 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 y to be evaluate
2b150 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f d..**.** Think o
2b160 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 f each SQL state
2b170 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 ment as a separa
2b180 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 te computer prog
2b190 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 ram. The.** ori
2b1a0 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 ginal SQL text i
2b1b0 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 s source code.
2b1c0 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 A prepared state
2b1d0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 ment object .**
2b1e0 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 is the compiled
2b1f0 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c object code. Al
2b200 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f l SQL must be co
2b210 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a nverted into a.*
2b220 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 * prepared state
2b230 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 ment before it c
2b240 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a an be run..**.**
2b250 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 The life-cycle
2b260 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 of a prepared st
2b270 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 atement object u
2b280 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 sually goes like
2b290 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c this:.**.** <ol
2b2a0 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 >.** <li> Create
2b2b0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
2b2c0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 atement object u
2b2d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 sing [sqlite3_pr
2b2e0 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 epare_v2()]..**
2b2f0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 <li> Bind values
2b300 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d to [parameters]
2b310 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 using the sqlit
2b320 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 e3_bind_*().**
2b330 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a interfaces..
2b340 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 ** <li> Run the
2b350 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b SQL by calling [
2b360 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2b370 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 one or more time
2b380 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 s..** <li> Reset
2b390 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
2b3a0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 atement using [s
2b3b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2b3c0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 then go back.**
2b3d0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 to step 2.
2b3e0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 Do this zero or
2b3f0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 more times..**
2b400 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 <li> Destroy the
2b410 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 object using [s
2b420 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2b430 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a )]..** </ol>.*/.
2b440 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
2b450 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 qlite3_stmt sqli
2b460 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a te3_stmt;../*.**
2b470 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 CAPI3REF: Run-t
2b480 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 ime Limits.** ME
2b490 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
2b4a0 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 .** ^(This inter
2b4b0 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 face allows the
2b4c0 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 size of various
2b4d0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 constructs to be
2b4e0 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 limited.** on a
2b4f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 connection by c
2b500 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e onnection basis.
2b510 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 The first para
2b520 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 meter is the.**
2b530 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2b540 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 tion] whose limi
2b550 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f t is to be set o
2b560 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a r queried. The.
2b570 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 ** second parame
2b580 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 ter is one of th
2b590 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 e [limit categor
2b5a0 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 ies] that define
2b5b0 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 a.** class of c
2b5c0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 onstructs to be
2b5d0 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 size limited. T
2b5e0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
2b5f0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 er is the.** new
2b600 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 limit for that
2b610 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a construct.)^.**.
2b620 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c ** ^If the new l
2b630 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 imit is a negati
2b640 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c ve number, the l
2b650 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 imit is unchange
2b660 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 d..** ^(For each
2b670 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 limit category
2b680 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e SQLITE_LIMIT_<i>
2b690 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 NAME</i> there i
2b6a0 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 s a .** [limits
2b6b0 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 | hard upper bou
2b6c0 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f nd].** set at co
2b6d0 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 mpile-time by a
2b6e0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
2b6f0 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b acro called.** [
2b700 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f limits | SQLITE_
2b710 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d MAX_<i>NAME</i>]
2b720 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 ..** (The "_LIMI
2b730 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 T_" in the name
2b740 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f is changed to "_
2b750 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 MAX_".))^.** ^At
2b760 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 tempts to increa
2b770 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 se a limit above
2b780 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 its hard upper
2b790 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c bound are.** sil
2b7a0 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 ently truncated
2b7b0 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 to the hard uppe
2b7c0 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e r bound..**.** ^
2b7d0 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 Regardless of wh
2b7e0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
2b7f0 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 limit was chang
2b800 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c ed, the .** [sql
2b810 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e ite3_limit()] in
2b820 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2b830 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 the prior value
2b840 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a of the limit..**
2b850 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 ^Hence, to find
2b860 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c the current val
2b870 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 ue of a limit wi
2b880 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 thout changing i
2b890 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 t,.** simply inv
2b8a0 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 oke this interfa
2b8b0 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 ce with the thir
2b8c0 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 d parameter set
2b8d0 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e to -1..**.** Run
2b8e0 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 -time limits are
2b8f0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
2b900 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e e in application
2b910 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a s that manage.**
2b920 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 both their own
2b930 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 internal databas
2b940 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 e and also datab
2b950 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f ases that are co
2b960 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 ntrolled.** by u
2b970 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 ntrusted externa
2b980 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 l sources. An e
2b990 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 xample applicati
2b9a0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a on might be a.**
2b9b0 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 web browser tha
2b9c0 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 t has its own da
2b9d0 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 tabases for stor
2b9e0 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a ing history and.
2b9f0 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 ** separate data
2ba00 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 bases controlled
2ba10 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 by JavaScript a
2ba20 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e pplications down
2ba30 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 loaded.** off th
2ba40 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 e Internet. The
2ba50 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 internal databa
2ba60 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e ses can be given
2ba70 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 the.** large, d
2ba80 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 efault limits.
2ba90 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 Databases manage
2baa0 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f d by external so
2bab0 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 urces can.** be
2bac0 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c given much small
2bad0 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e er limits design
2bae0 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 ed to prevent a
2baf0 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 denial of servic
2bb00 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 e.** attack. De
2bb10 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 velopers might a
2bb20 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 lso want to use
2bb30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 the [sqlite3_set
2bb40 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a _authorizer()].*
2bb50 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 * interface to f
2bb60 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 urther control u
2bb70 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 ntrusted SQL. T
2bb80 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 he size of the d
2bb90 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 atabase.** creat
2bba0 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 ed by an untrust
2bbb0 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 ed script can be
2bbc0 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 contained using
2bbd0 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 the.** [max_pag
2bbe0 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 e_count] [PRAGMA
2bbf0 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e ]..**.** New run
2bc00 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 -time limit cate
2bc10 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 gories may be ad
2bc20 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
2bc30 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 leases..*/.int s
2bc40 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c qlite3_limit(sql
2bc50 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 ite3*, int id, i
2bc60 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a nt newVal);../*.
2bc70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
2bc80 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 -Time Limit Cate
2bc90 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 gories.** KEYWOR
2bca0 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 DS: {limit categ
2bcb0 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 ory} {*limit cat
2bcc0 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 egories}.**.** T
2bcd0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 hese constants d
2bce0 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 efine various pe
2bcf0 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 rformance limits
2bd00 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 .** that can be
2bd10 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 lowered at run-t
2bd20 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ime using [sqlit
2bd30 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 e3_limit()]..**
2bd40 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 The synopsis of
2bd50 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 the meanings of
2bd60 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 the various limi
2bd70 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f ts is shown belo
2bd80 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c w..** Additional
2bd90 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
2bda0 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 available at [li
2bdb0 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e mits | Limits in
2bdc0 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 SQLite]..**.**
2bdd0 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 <dl>.** [[SQLITE
2bde0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 _LIMIT_LENGTH]]
2bdf0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
2be00 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a IT_LENGTH</dt>.*
2be10 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
2be20 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 m size of any st
2be30 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 ring or BLOB or
2be40 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 table row, in by
2be50 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a tes.<dd>)^.**.**
2be60 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
2be70 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c SQL_LENGTH]] ^(<
2be80 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
2be90 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a SQL_LENGTH</dt>.
2bea0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
2beb0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 um length of an
2bec0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 SQL statement, i
2bed0 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a n bytes.</dd>)^.
2bee0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
2bef0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 IMIT_COLUMN]] ^(
2bf00 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
2bf10 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 _COLUMN</dt>.**
2bf20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
2bf30 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
2bf40 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 s in a table def
2bf50 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 inition or in th
2bf60 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 e.** result set
2bf70 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 of a [SELECT] or
2bf80 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d the maximum num
2bf90 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
2bfa0 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 n an index.** or
2bfb0 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 in an ORDER BY
2bfc0 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 or GROUP BY clau
2bfd0 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a se.</dd>)^.**.**
2bfe0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
2bff0 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c EXPR_DEPTH]] ^(<
2c000 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
2c010 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a EXPR_DEPTH</dt>.
2c020 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
2c030 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 um depth of the
2c040 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e parse tree on an
2c050 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 y expression.</d
2c060 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
2c070 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
2c080 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 ND_SELECT]] ^(<d
2c090 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 t>SQLITE_LIMIT_C
2c0a0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f OMPOUND_SELECT</
2c0b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
2c0c0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
2c0d0 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 terms in a comp
2c0e0 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 ound SELECT stat
2c0f0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ement.</dd>)^.**
2c100 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
2c110 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c IT_VDBE_OP]] ^(<
2c120 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
2c130 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 VDBE_OP</dt>.**
2c140 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
2c150 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 number of instru
2c160 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 ctions in a virt
2c170 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 ual machine prog
2c180 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 ram.** used to i
2c190 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 mplement an SQL
2c1a0 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b statement. If [
2c1b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2c1c0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 v2()] or.** the
2c1d0 65 71 75 69 76 61 6c 65 6e 74 20 74 72 69 65 73 equivalent tries
2c1e0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 to allocate spa
2c1f0 63 65 20 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e ce for more than
2c200 20 74 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 this many opcod
2c210 65 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c es.** in a singl
2c220 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
2c230 6d 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f ment, an SQLITE_
2c240 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73 20 72 NOMEM error is r
2c250 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a eturned.</dd>)^.
2c260 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
2c270 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
2c280 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 G]] ^(<dt>SQLITE
2c290 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
2c2a0 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ARG</dt>.** <dd>
2c2b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
2c2c0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
2c2d0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f on a function.</
2c2e0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
2c2f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 LITE_LIMIT_ATTAC
2c300 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 HED]] ^(<dt>SQLI
2c310 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 TE_LIMIT_ATTACHE
2c320 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
2c330 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
2c340 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 of [ATTACH | at
2c350 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 tached databases
2c360 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ].)^</dd>.**.**
2c370 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c [[SQLITE_LIMIT_L
2c380 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
2c390 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 TH]].** ^(<dt>SQ
2c3a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f LITE_LIMIT_LIKE_
2c3b0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f PATTERN_LENGTH</
2c3c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
2c3d0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
2c3e0 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 the pattern arg
2c3f0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 ument to the [LI
2c400 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d KE] or.** [GLOB]
2c410 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e operators.</dd>
2c420 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
2c430 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
2c440 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c _NUMBER]].** ^(<
2c450 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
2c460 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c VARIABLE_NUMBER<
2c470 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
2c480 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 maximum index nu
2c490 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 mber of any [par
2c4a0 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 ameter] in an SQ
2c4b0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a L statement.)^.*
2c4c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
2c4d0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 MIT_TRIGGER_DEPT
2c4e0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 H]] ^(<dt>SQLITE
2c4f0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 _LIMIT_TRIGGER_D
2c500 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 EPTH</dt>.** <dd
2c510 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 >The maximum dep
2c520 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 th of recursion
2c530 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 for triggers.</d
2c540 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
2c550 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 ITE_LIMIT_WORKER
2c560 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 _THREADS]] ^(<dt
2c570 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f >SQLITE_LIMIT_WO
2c580 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 RKER_THREADS</dt
2c590 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
2c5a0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 imum number of a
2c5b0 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 uxiliary worker
2c5c0 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73 threads that a s
2c5d0 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 ingle.** [prepar
2c5e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 ed statement] ma
2c5f0 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a y start.</dd>)^.
2c600 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
2c610 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
2c620 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 _LENGTH
2c630 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 0.#de
2c640 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
2c650 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 T_SQL_LENGTH
2c660 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 1.#d
2c670 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
2c680 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 IT_COLUMN
2c690 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 2.#
2c6a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
2c6b0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 MIT_EXPR_DEPTH
2c6c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 3.
2c6d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
2c6e0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
2c6f0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 LECT 4
2c700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2c710 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 LIMIT_VDBE_OP
2c720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2c730 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
2c740 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
2c750 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 ARG
2c760 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 6.#define SQLIT
2c770 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 E_LIMIT_ATTACHED
2c780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2c790 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 7.#define SQLI
2c7a0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 TE_LIMIT_LIKE_PA
2c7b0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 TTERN_LENGTH
2c7c0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 8.#define SQL
2c7d0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
2c7e0 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 LE_NUMBER
2c7f0 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 9.#define SQ
2c800 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
2c810 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 ER_DEPTH
2c820 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 10.#define S
2c830 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b QLITE_LIMIT_WORK
2c840 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 ER_THREADS
2c850 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 11../*.** C
2c860 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 API3REF: Prepare
2c870 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 Flags.**.** The
2c880 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 se constants def
2c890 69 6e 65 20 76 61 72 69 6f 75 73 20 66 6c 61 67 ine various flag
2c8a0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 61 s that can be pa
2c8b0 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72 ssed into.** "pr
2c8c0 65 70 46 6c 61 67 73 22 20 70 61 72 61 6d 65 74 epFlags" paramet
2c8d0 65 72 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 er of the [sqlit
2c8e0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d e3_prepare_v3()]
2c8f0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
2c900 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d _prepare16_v3()]
2c910 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a interfaces..**.
2c920 2a 2a 20 4e 65 77 20 66 6c 61 67 73 20 6d 61 79 ** New flags may
2c930 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
2c940 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
2c950 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 SQLite..**.** <d
2c960 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 l>.** [[SQLITE_P
2c970 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e REPARE_PERSISTEN
2c980 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 T]] ^(<dt>SQLITE
2c990 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 _PREPARE_PERSIST
2c9a0 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ENT</dt>.** <dd>
2c9b0 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 The SQLITE_PREPA
2c9c0 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 66 6c RE_PERSISTENT fl
2c9d0 61 67 20 69 73 20 61 20 68 69 6e 74 20 74 6f 20 ag is a hint to
2c9e0 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 the query planne
2c9f0 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 r.** that the pr
2ca00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2ca10 20 77 69 6c 6c 20 62 65 20 72 65 74 61 69 6e 65 will be retaine
2ca20 64 20 66 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d d for a long tim
2ca30 65 20 61 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c e and.** probabl
2ca40 79 20 72 65 75 73 65 64 20 6d 61 6e 79 20 74 69 y reused many ti
2ca50 6d 65 73 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20 mes.)^ ^Without
2ca60 74 68 69 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69 this flag, [sqli
2ca70 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 te3_prepare_v3()
2ca80 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
2ca90 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 3_prepare16_v3()
2caa0 5d 20 61 73 73 75 6d 65 20 74 68 61 74 20 74 68 ] assume that th
2cab0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
2cac0 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65 ment will .** be
2cad0 20 75 73 65 64 20 6a 75 73 74 20 6f 6e 63 65 20 used just once
2cae0 6f 72 20 61 74 20 6d 6f 73 74 20 61 20 66 65 77 or at most a few
2caf0 20 74 69 6d 65 73 20 61 6e 64 20 74 68 65 6e 20 times and then
2cb00 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a destroyed using.
2cb10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ** [sqlite3_fina
2cb20 6c 69 7a 65 28 29 5d 20 72 65 6c 61 74 69 76 65 lize()] relative
2cb30 6c 79 20 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72 ly soon. The cur
2cb40 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 rent implementat
2cb50 69 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74 ion acts.** on t
2cb60 68 69 73 20 68 69 6e 74 20 62 79 20 61 76 6f 69 his hint by avoi
2cb70 64 69 6e 67 20 74 68 65 20 75 73 65 20 6f 66 20 ding the use of
2cb80 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 [lookaside memor
2cb90 79 5d 20 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a y] so as not to.
2cba0 2a 2a 20 64 65 70 6c 65 74 65 20 74 68 65 20 6c ** deplete the l
2cbb0 69 6d 69 74 65 64 20 73 74 6f 72 65 20 6f 66 20 imited store of
2cbc0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
2cbd0 2e 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e . Future version
2cbe0 73 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d s of.** SQLite m
2cbf0 61 79 20 61 63 74 20 6f 6e 20 74 68 69 73 20 68 ay act on this h
2cc00 69 6e 74 20 64 69 66 66 65 72 65 6e 74 6c 79 2e int differently.
2cc10 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
2cc20 50 52 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a PREPARE_NORMALIZ
2cc30 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 50 E]] <dt>SQLITE_P
2cc40 52 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 REPARE_NORMALIZE
2cc50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
2cc60 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f SQLITE_PREPARE_
2cc70 4e 4f 52 4d 41 4c 49 5a 45 20 66 6c 61 67 20 69 NORMALIZE flag i
2cc80 73 20 61 20 6e 6f 2d 6f 70 2e 20 54 68 69 73 20 s a no-op. This
2cc90 66 6c 61 67 20 75 73 65 64 0a 2a 2a 20 74 6f 20 flag used.** to
2cca0 62 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 be required for
2ccb0 61 6e 79 20 70 72 65 70 61 72 65 64 20 73 74 61 any prepared sta
2ccc0 74 65 6d 65 6e 74 20 74 68 61 74 20 77 61 6e 74 tement that want
2ccd0 65 64 20 74 6f 20 75 73 65 20 74 68 65 0a 2a 2a ed to use the.**
2cce0 20 5b 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c [sqlite3_normal
2ccf0 69 7a 65 64 5f 73 71 6c 28 29 5d 20 69 6e 74 65 ized_sql()] inte
2cd00 72 66 61 63 65 2e 20 20 48 6f 77 65 76 65 72 2c rface. However,
2cd10 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
2cd20 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 _normalized_sql(
2cd30 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 )] interface is
2cd40 6e 6f 77 20 61 76 61 69 6c 61 62 6c 65 20 74 6f now available to
2cd50 20 61 6c 6c 0a 2a 2a 20 70 72 65 70 61 72 65 64 all.** prepared
2cd60 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 72 65 67 statements, reg
2cd70 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
2cd80 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 79 20 75 er or not they u
2cd90 73 65 20 74 68 69 73 0a 2a 2a 20 66 6c 61 67 2e se this.** flag.
2cda0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
2cdb0 50 52 45 50 41 52 45 5f 4e 4f 5f 56 54 41 42 5d PREPARE_NO_VTAB]
2cdc0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 ] <dt>SQLITE_PRE
2cdd0 50 41 52 45 5f 4e 4f 5f 56 54 41 42 3c 2f 64 74 PARE_NO_VTAB</dt
2cde0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c >.** <dd>The SQL
2cdf0 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 5f 56 ITE_PREPARE_NO_V
2ce00 54 41 42 20 66 6c 61 67 20 63 61 75 73 65 73 20 TAB flag causes
2ce10 74 68 65 20 53 51 4c 20 63 6f 6d 70 69 6c 65 72 the SQL compiler
2ce20 0a 2a 2a 20 74 6f 20 72 65 74 75 72 6e 20 61 6e .** to return an
2ce30 20 65 72 72 6f 72 20 28 65 72 72 6f 72 20 63 6f error (error co
2ce40 64 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 29 de SQLITE_ERROR)
2ce50 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e if the statemen
2ce60 74 20 75 73 65 73 0a 2a 2a 20 61 6e 79 20 76 69 t uses.** any vi
2ce70 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a rtual tables..**
2ce80 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </dl>.*/.#defin
2ce90 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 e SQLITE_PREPARE
2cea0 5f 50 45 52 53 49 53 54 45 4e 54 20 20 20 20 20 _PERSISTENT
2ceb0 20 20 20 20 20 20 20 20 20 30 78 30 31 0a 23 64 0x01.#d
2cec0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 efine SQLITE_PRE
2ced0 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 20 20 PARE_NORMALIZE
2cee0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
2cef0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
2cf00 5f 50 52 45 50 41 52 45 5f 4e 4f 5f 56 54 41 42 _PREPARE_NO_VTAB
2cf10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2cf20 20 30 78 30 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 0x04../*.** CAP
2cf30 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 I3REF: Compiling
2cf40 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
2cf50 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b t.** KEYWORDS: {
2cf60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f SQL statement co
2cf70 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f mpiler}.** METHO
2cf80 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f D: sqlite3.** CO
2cf90 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 NSTRUCTOR: sqlit
2cfa0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f e3_stmt.**.** To
2cfb0 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 execute an SQL
2cfc0 73 74 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 statement, it mu
2cfd0 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 st first be comp
2cfe0 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 iled into a byte
2cff0 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d -code.** program
2d000 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 using one of th
2d010 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f ese routines. O
2d020 72 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 r, in other word
2d030 73 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 s, these routine
2d040 73 0a 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 s.** are constru
2d050 63 74 6f 72 73 20 66 6f 72 20 74 68 65 20 5b 70 ctors for the [p
2d060 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2d070 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a t] object..**.**
2d080 20 54 68 65 20 70 72 65 66 65 72 72 65 64 20 72 The preferred r
2d090 6f 75 74 69 6e 65 20 74 6f 20 75 73 65 20 69 73 outine to use is
2d0a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2d0b0 65 5f 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a e_v2()]. The.**
2d0c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2d0d0 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 e()] interface i
2d0e0 73 20 6c 65 67 61 63 79 20 61 6e 64 20 73 68 6f s legacy and sho
2d0f0 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a uld be avoided..
2d100 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
2d110 61 72 65 5f 76 33 28 29 5d 20 68 61 73 20 61 6e are_v3()] has an
2d120 20 65 78 74 72 61 20 22 70 72 65 70 46 6c 61 67 extra "prepFlag
2d130 73 22 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 s" option that i
2d140 73 20 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 s used.** for sp
2d150 65 63 69 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a ecial purposes..
2d160 2a 2a 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 **.** The use of
2d170 20 74 68 65 20 55 54 46 2d 38 20 69 6e 74 65 72 the UTF-8 inter
2d180 66 61 63 65 73 20 69 73 20 70 72 65 66 65 72 72 faces is preferr
2d190 65 64 2c 20 61 73 20 53 51 4c 69 74 65 20 63 75 ed, as SQLite cu
2d1a0 72 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 rrently.** does
2d1b0 61 6c 6c 20 70 61 72 73 69 6e 67 20 75 73 69 6e all parsing usin
2d1c0 67 20 55 54 46 2d 38 2e 20 20 54 68 65 20 55 54 g UTF-8. The UT
2d1d0 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 F-16 interfaces
2d1e0 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 are provided.**
2d1f0 61 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 as a convenience
2d200 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e . The UTF-16 in
2d210 74 65 72 66 61 63 65 73 20 77 6f 72 6b 20 62 79 terfaces work by
2d220 20 63 6f 6e 76 65 72 74 69 6e 67 20 74 68 65 0a converting the.
2d230 2a 2a 20 69 6e 70 75 74 20 74 65 78 74 20 69 6e ** input text in
2d240 74 6f 20 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 to UTF-8, then i
2d250 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 nvoking the corr
2d260 65 73 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 esponding UTF-8
2d270 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
2d280 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
2d290 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 ent, "db", is a
2d2a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2d2b0 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 tion] obtained f
2d2c0 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 rom a.** prior s
2d2d0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
2d2e0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
2d2f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
2d300 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 n_v2()] or.** [s
2d310 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
2d320 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 . The database
2d330 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 connection must
2d340 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c not have been cl
2d350 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 osed..**.** The
2d360 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c second argument,
2d370 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 "zSql", is the
2d380 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 statement to be
2d390 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 compiled, encode
2d3a0 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 d.** as either U
2d3b0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 TF-8 or UTF-16.
2d3c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 The sqlite3_pre
2d3d0 70 61 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f pare(), sqlite3_
2d3e0 70 72 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a prepare_v2(),.**
2d3f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
2d400 70 61 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 pare_v3().** int
2d410 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d erfaces use UTF-
2d420 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 8, and sqlite3_p
2d430 72 65 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69 repare16(), sqli
2d440 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
2d450 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 (),.** and sqlit
2d460 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 e3_prepare16_v3(
2d470 29 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a ) use UTF-16..**
2d480 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 .** ^If the nByt
2d490 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 e argument is ne
2d4a0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 gative, then zSq
2d4b0 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 l is read up to
2d4c0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 the.** first zer
2d4d0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 o terminator. ^I
2d4e0 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 f nByte is posit
2d4f0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 ive, then it is
2d500 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
2d510 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d bytes read from
2d520 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 zSql. ^If nByt
2d530 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 e is zero, then
2d540 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 no prepared.** s
2d550 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 tatement is gene
2d560 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 rated..** If the
2d570 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 caller knows th
2d580 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 at the supplied
2d590 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 string is nul-te
2d5a0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a rminated, then.*
2d5b0 2a 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 * there is a sma
2d5c0 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 ll performance a
2d5d0 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 dvantage to pass
2d5e0 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 ing an nByte par
2d5f0 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 ameter that.** i
2d600 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
2d610 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 bytes in the inp
2d620 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 ut string <i>inc
2d630 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 luding</i>.** th
2d640 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 e nul-terminator
2d650 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 ..**.** ^If pzTa
2d660 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 il is not NULL t
2d670 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d hen *pzTail is m
2d680 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 ade to point to
2d690 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a the first byte.*
2d6a0 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f * past the end o
2d6b0 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 f the first SQL
2d6c0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 statement in zSq
2d6d0 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e l. These routin
2d6e0 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 es only.** compi
2d6f0 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 le the first sta
2d700 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 tement in zSql,
2d710 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 so *pzTail is le
2d720 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a ft pointing to.*
2d730 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 * what remains u
2d740 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a ncompiled..**.**
2d750 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 ^*ppStmt is lef
2d760 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 t pointing to a
2d770 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 compiled [prepar
2d780 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
2d790 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 at can be.** exe
2d7a0 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c cuted using [sql
2d7b0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e ite3_step()]. ^
2d7c0 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 If there is an e
2d7d0 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 rror, *ppStmt is
2d7e0 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e set.** to NULL.
2d7f0 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 ^If the input
2d800 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f text contains no
2d810 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 SQL (if the inp
2d820 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a ut is an empty.*
2d830 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f * string or a co
2d840 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 mment) then *ppS
2d850 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 tmt is set to NU
2d860 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 LL..** The calli
2d870 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 ng procedure is
2d880 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 responsible for
2d890 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d deleting the com
2d8a0 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 piled.** SQL sta
2d8b0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 tement using [sq
2d8c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
2d8d0 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 ] after it has f
2d8e0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e inished with it.
2d8f0 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e .** ppStmt may n
2d900 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a ot be NULL..**.*
2d910 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 * ^On success, t
2d920 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 he sqlite3_prepa
2d930 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 re() family of r
2d940 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b outines return [
2d950 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f SQLITE_OK];.** o
2d960 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 therwise an [err
2d970 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
2d980 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rned..**.** The
2d990 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2d9a0 76 32 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 v2(), sqlite3_pr
2d9b0 65 70 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 epare_v3(), sqli
2d9c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
2d9d0 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 (),.** and sqlit
2d9e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 e3_prepare16_v3(
2d9f0 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 ) interfaces are
2da00 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 recommended for
2da10 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d all new program
2da20 73 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 s..** The older
2da30 69 6e 74 65 72 66 61 63 65 73 20 28 73 71 6c 69 interfaces (sqli
2da40 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e te3_prepare() an
2da50 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
2da60 65 31 36 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 e16()).** are re
2da70 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 tained for backw
2da80 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
2da90 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 ty, but their us
2daa0 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 e is discouraged
2dab0 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 ..** ^In the "vX
2dac0 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 " interfaces, th
2dad0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
2dae0 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 ment.** that is
2daf0 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 returned (the [s
2db00 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a qlite3_stmt] obj
2db10 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 ect) contains a
2db20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f copy of the.** o
2db30 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 riginal SQL text
2db40 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 . This causes th
2db50 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
2db60 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a )] interface to.
2db70 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 ** behave differ
2db80 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 ently in three w
2db90 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a ays:.**.** <ol>.
2dba0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 ** <li>.** ^If t
2dbb0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 he database sche
2dbc0 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 ma changes, inst
2dbd0 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 ead of returning
2dbe0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
2dbf0 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 as it.** always
2dc00 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 used to do, [sq
2dc10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
2dc20 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ll automatically
2dc30 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 recompile the S
2dc40 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 QL.** statement
2dc50 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 and try to run i
2dc60 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 t again. As many
2dc70 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f as [SQLITE_MAX_
2dc80 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a SCHEMA_RETRY].**
2dc90 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 retries will oc
2dca0 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 cur before sqlit
2dcb0 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 e3_step() gives
2dcc0 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 up and returns a
2dcd0 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 n error..** </li
2dce0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 >.**.** <li>.**
2dcf0 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f ^When an error o
2dd00 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f ccurs, [sqlite3_
2dd10 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 step()] will ret
2dd20 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 urn one of the d
2dd30 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f etailed.** [erro
2dd40 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 r codes] or [ext
2dd50 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
2dd60 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 s]. ^The legacy
2dd70 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 behavior was th
2dd80 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 at.** [sqlite3_s
2dd90 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c tep()] would onl
2dda0 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 y return a gener
2ddb0 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ic [SQLITE_ERROR
2ddc0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a ] result code.**
2ddd0 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 and the applica
2dde0 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 tion would have
2ddf0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 to make a second
2de00 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
2de10 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 3_reset()].** in
2de20 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 order to find t
2de30 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 he underlying ca
2de40 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c use of the probl
2de50 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 em. With the "v2
2de60 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 " prepare.** int
2de70 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 erfaces, the und
2de80 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 erlying reason f
2de90 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 or the error is
2dea0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 returned immedia
2deb0 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a tely..** </li>.*
2dec0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 *.** <li>.** ^If
2ded0 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 the specific va
2dee0 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 lue bound to [pa
2def0 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 rameter | host p
2df00 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 arameter] in the
2df10 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 .** WHERE claus
2df20 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 e might influenc
2df30 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 e the choice of
2df40 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 query plan for a
2df50 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 statement,.** t
2df60 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e hen the statemen
2df70 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 t will be automa
2df80 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c tically recompil
2df90 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 ed, as if there
2dfa0 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 had been .** a s
2dfb0 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e chema change, on
2dfc0 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c the first [sql
2dfd0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c ite3_step()] cal
2dfe0 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 l following any
2dff0 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 change.** to the
2e000 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 [sqlite3_bind_t
2e010 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 ext | bindings]
2e020 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 of that [paramet
2e030 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 er]. .** ^The sp
2e040 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 ecific value of
2e050 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 WHERE-clause [pa
2e060 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 rameter] might i
2e070 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a nfluence the .**
2e080 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 choice of query
2e090 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 plan if the par
2e0a0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 ameter is the le
2e0b0 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 ft-hand side of
2e0c0 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b a [LIKE].** or [
2e0d0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f GLOB] operator o
2e0e0 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 r if the paramet
2e0f0 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 er is compared t
2e100 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c o an indexed col
2e110 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b umn.** and the [
2e120 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 SQLITE_ENABLE_ST
2e130 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d AT3] compile-tim
2e140 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 e option is enab
2e150 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a led..** </li>.**
2e160 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e </ol>.**.** <p>
2e170 5e 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 ^sqlite3_prepare
2e180 5f 76 33 28 29 20 64 69 66 66 65 72 73 20 66 72 _v3() differs fr
2e190 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 om sqlite3_prepa
2e1a0 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20 re_v2() only in
2e1b0 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78 having.** the ex
2e1c0 74 72 61 20 70 72 65 70 46 6c 61 67 73 20 70 61 tra prepFlags pa
2e1d0 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 69 rameter, which i
2e1e0 73 20 61 20 62 69 74 20 61 72 72 61 79 20 63 6f s a bit array co
2e1f0 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f nsisting of zero
2e200 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 or.** more of t
2e210 68 65 20 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 he [SQLITE_PREPA
2e220 52 45 5f 50 45 52 53 49 53 54 45 4e 54 7c 53 51 RE_PERSISTENT|SQ
2e230 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20 LITE_PREPARE_*]
2e240 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 flags. ^The.**
2e250 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2e260 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 v2() interface w
2e270 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 74 68 65 orks exactly the
2e280 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 same as.** sqli
2e290 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 te3_prepare_v3()
2e2a0 20 77 69 74 68 20 61 20 7a 65 72 6f 20 70 72 65 with a zero pre
2e2b0 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 pFlags parameter
2e2c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2e2d0 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 _prepare(. sqli
2e2e0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
2e2f0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
2e300 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
2e310 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 t char *zSql,
2e320 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
2e330 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f ment, UTF-8 enco
2e340 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
2e350 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
2e360 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
2e370 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
2e380 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
2e390 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
2e3a0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
2e3b0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
2e3c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 const char **pzT
2e3d0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
2e3e0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
2e3f0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
2e400 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 l */.);.int sqli
2e410 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a te3_prepare_v2(.
2e420 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
2e430 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
2e440 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
2e450 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
2e460 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
2e470 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
2e480 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 8 encoded */. i
2e490 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
2e4a0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
2e4b0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
2e4c0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
2e4d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
2e4e0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
2e4f0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
2e500 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
2e510 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
2e520 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
2e530 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
2e540 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e of zSql */.);.in
2e550 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
2e560 65 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 e_v3(. sqlite3
2e570 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
2e580 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
2e590 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
2e5a0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 ar *zSql,
2e5b0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
2e5c0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 , UTF-8 encoded
2e5d0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 */. int nByte,
2e5e0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
2e5f0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f Maximum length o
2e600 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e f zSql in bytes.
2e610 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 */. unsigned i
2e620 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a nt prepFlags, /*
2e630 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 Zero or more SQ
2e640 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c LITE_PREPARE_ fl
2e650 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 ags */. sqlite3
2e660 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
2e670 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
2e680 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
2e690 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 onst char **pzTa
2e6a0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
2e6b0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
2e6c0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
2e6d0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
2e6e0 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 e3_prepare16(.
2e6f0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
2e700 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
2e710 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
2e720 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c const void *zSql
2e730 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
2e740 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 tatement, UTF-16
2e750 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
2e760 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
2e770 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
2e780 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
2e790 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
2e7a0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
2e7b0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
2e7c0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
2e7d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
2e7e0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
2e7f0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
2e800 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
2e810 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 f zSql */.);.int
2e820 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
2e830 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 16_v2(. sqlite3
2e840 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
2e850 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
2e860 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
2e870 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 oid *zSql,
2e880 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
2e890 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 t, UTF-16 encode
2e8a0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
2e8b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
2e8c0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
2e8d0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
2e8e0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
2e8f0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
2e900 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
2e910 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
2e920 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 nst void **pzTai
2e930 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
2e940 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
2e950 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
2e960 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 */.);.int sqlite
2e970 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a 3_prepare16_v3(.
2e980 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
2e990 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
2e9a0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
2e9b0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 const void *zS
2e9c0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
2e9d0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
2e9e0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 16 encoded */.
2e9f0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
2ea00 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
2ea10 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
2ea20 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
2ea30 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 unsigned int pr
2ea40 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f epFlags, /* Zero
2ea50 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f or more SQLITE_
2ea60 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a PREPARE_ flags *
2ea70 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
2ea80 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
2ea90 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
2eaa0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
2eab0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
2eac0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
2ead0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
2eae0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
2eaf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2eb00 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 F: Retrieving St
2eb10 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d atement SQL.** M
2eb20 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
2eb30 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 tmt.**.** ^The s
2eb40 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e qlite3_sql(P) in
2eb50 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2eb60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 a pointer to a c
2eb70 6f 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 opy of the UTF-8
2eb80 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 .** SQL text use
2eb90 64 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 d to create [pre
2eba0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2ebb0 20 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 P if P was.** c
2ebc0 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 reated by [sqlit
2ebd0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2ebe0 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 , [sqlite3_prepa
2ebf0 72 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 re_v3()],.** [sq
2ec00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2ec10 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 v2()], or [sqlit
2ec20 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 e3_prepare16_v3(
2ec30 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 )]..** ^The sqli
2ec40 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c te3_expanded_sql
2ec50 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (P) interface re
2ec60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
2ec70 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 to a UTF-8.** st
2ec80 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 ring containing
2ec90 74 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 the SQL text of
2eca0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2ecb0 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f nt P with.** [bo
2ecc0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 und parameters]
2ecd0 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 20 5e 54 68 expanded..** ^Th
2ece0 65 20 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c e sqlite3_normal
2ecf0 69 7a 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 ized_sql(P) inte
2ed00 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
2ed10 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 pointer to a UTF
2ed20 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e -8.** string con
2ed30 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 6f 72 6d taining the norm
2ed40 61 6c 69 7a 65 64 20 53 51 4c 20 74 65 78 74 20 alized SQL text
2ed50 6f 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 of prepared stat
2ed60 65 6d 65 6e 74 20 50 2e 20 20 54 68 65 0a 2a 2a ement P. The.**
2ed70 20 73 65 6d 61 6e 74 69 63 73 20 75 73 65 64 20 semantics used
2ed80 74 6f 20 6e 6f 72 6d 61 6c 69 7a 65 20 61 20 53 to normalize a S
2ed90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 QL statement are
2eda0 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 unspecified and
2edb0 20 73 75 62 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 subject.** to c
2edc0 68 61 6e 67 65 2e 20 20 41 74 20 61 20 6d 69 6e hange. At a min
2edd0 69 6d 75 6d 2c 20 6c 69 74 65 72 61 6c 20 76 61 imum, literal va
2ede0 6c 75 65 73 20 77 69 6c 6c 20 62 65 20 72 65 70 lues will be rep
2edf0 6c 61 63 65 64 20 77 69 74 68 20 73 75 69 74 61 laced with suita
2ee00 62 6c 65 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 ble.** placehold
2ee10 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 ers..**.** ^(For
2ee20 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 example, if a p
2ee30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2ee40 74 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 t is created usi
2ee50 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 ng the SQL.** te
2ee60 78 74 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c xt "SELECT $abc,
2ee70 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72 :xyz" and if par
2ee80 61 6d 65 74 65 72 20 24 61 62 63 20 69 73 20 62 ameter $abc is b
2ee90 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20 ound to integer
2eea0 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 2345.** and para
2eeb0 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e meter :xyz is un
2eec0 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 bound, then sqli
2eed0 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 te3_sql() will r
2eee0 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 eturn.** the ori
2eef0 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 ginal string, "S
2ef00 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 ELECT $abc,:xyz"
2ef10 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70 but sqlite3_exp
2ef20 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 anded_sql().** w
2ef30 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45 ill return "SELE
2ef40 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e CT 2345,NULL".)^
2ef50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2ef60 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c te3_expanded_sql
2ef70 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
2ef80 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 urns NULL if ins
2ef90 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 ufficient memory
2efa0 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65 .** is available
2efb0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 to hold the res
2efc0 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72 ult, or if the r
2efd0 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 esult would exce
2efe0 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 ed the.** the ma
2eff0 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e ximum string len
2f000 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62 gth determined b
2f010 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 y the [SQLITE_LI
2f020 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a MIT_LENGTH]..**.
2f030 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
2f040 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 TRACE_SIZE_LIMIT
2f050 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
2f060 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 ption limits the
2f070 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e size of.** boun
2f080 64 20 70 61 72 61 6d 65 74 65 72 20 65 78 70 61 d parameter expa
2f090 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 nsions. ^The [S
2f0a0 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 QLITE_OMIT_TRACE
2f0b0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a ] compile-time.*
2f0c0 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20 * option causes
2f0d0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 sqlite3_expanded
2f0e0 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 _sql() to always
2f0f0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a return NULL..**
2f100 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 73 .** ^The strings
2f110 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
2f120 69 74 65 33 5f 73 71 6c 28 50 29 20 61 6e 64 20 ite3_sql(P) and
2f130 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a sqlite3_normaliz
2f140 65 64 5f 73 71 6c 28 50 29 0a 2a 2a 20 61 72 65 ed_sql(P).** are
2f150 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69 managed by SQLi
2f160 74 65 20 61 6e 64 20 61 72 65 20 61 75 74 6f 6d te and are autom
2f170 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77 atically freed w
2f180 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 hen the prepared
2f190 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 .** statement is
2f1a0 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e finalized..** ^
2f1b0 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 The string retur
2f1c0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 ned by sqlite3_e
2f1d0 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 xpanded_sql(P),
2f1e0 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e on the other han
2f1f0 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 d,.** is obtaine
2f200 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
2f210 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 malloc()] and mu
2f220 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68 st be free by th
2f230 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a e application.**
2f240 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 by passing it t
2f250 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
2f260 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 )]..*/.const cha
2f270 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 r *sqlite3_sql(s
2f280 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
2f290 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 mt);.char *sqlit
2f2a0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 e3_expanded_sql(
2f2b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
2f2c0 74 6d 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 tmt);.const char
2f2d0 20 2a 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c *sqlite3_normal
2f2e0 69 7a 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 ized_sql(sqlite3
2f2f0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
2f300 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2f310 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 Determine If An
2f320 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 SQL Statement Wr
2f330 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 ites The Databas
2f340 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c e.** METHOD: sql
2f350 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
2f360 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d ^The sqlite3_stm
2f370 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e t_readonly(X) in
2f380 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2f390 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 true (non-zero)
2f3a0 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 if.** and only i
2f3b0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 f the [prepared
2f3c0 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b statement] X mak
2f3d0 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 es no direct cha
2f3e0 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 nges to.** the c
2f3f0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 ontent of the da
2f400 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a tabase file..**.
2f410 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 ** Note that [ap
2f420 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2f430 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
2f440 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 or.** [virtual
2f450 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 tables] might ch
2f460 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 ange the databas
2f470 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 e indirectly as
2f480 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 a side effect.
2f490 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c .** ^(For exampl
2f4a0 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 e, if an applica
2f4b0 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 tion defines a f
2f4c0 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 unction "eval()"
2f4d0 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 that .** calls
2f4e0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
2f4f0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f , then the follo
2f500 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 wing SQL stateme
2f510 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e nt would.** chan
2f520 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ge the database
2f530 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 file through sid
2f540 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a e-effects:.**.**
2f550 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
2f560 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 e>.** SELECT
2f570 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f eval('DELETE FRO
2f580 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a M t1') FROM t2;.
2f590 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
2f5a0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 quote>.**.** But
2f5b0 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 because the [SE
2f5c0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 LECT] statement
2f5d0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 does not change
2f5e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
2f5f0 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 e.** directly, s
2f600 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
2f610 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 only() would sti
2f620 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 ll return true.)
2f630 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 ^.**.** ^Transac
2f640 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 tion control sta
2f650 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 tements such as
2f660 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 [BEGIN], [COMMIT
2f670 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a ], [ROLLBACK],.*
2f680 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 * [SAVEPOINT], a
2f690 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 nd [RELEASE] cau
2f6a0 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f se sqlite3_stmt_
2f6b0 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 readonly() to re
2f6c0 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 turn true,.** si
2f6d0 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e nce the statemen
2f6e0 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f ts themselves do
2f6f0 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f not actually mo
2f700 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 dify the databas
2f710 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 e but.** rather
2f720 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 they control the
2f730 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 timing of when
2f740 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 other statements
2f750 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 modify the .**
2f760 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 database. ^The
2f770 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 [ATTACH] and [DE
2f780 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 TACH] statements
2f790 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 also cause.** s
2f7a0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
2f7b0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e only() to return
2f7c0 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 true since, whi
2f7d0 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 le those stateme
2f7e0 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 nts.** change th
2f7f0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 e configuration
2f800 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f of a database co
2f810 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 nnection, they d
2f820 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 o not make .** c
2f830 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f hanges to the co
2f840 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 ntent of the dat
2f850 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 abase files on d
2f860 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c isk..** ^The sql
2f870 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
2f880 6c 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ly() interface r
2f890 65 74 75 72 6e 73 20 74 72 75 65 20 66 6f 72 20 eturns true for
2f8a0 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a [BEGIN] since.**
2f8b0 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 [BEGIN] merely
2f8c0 73 65 74 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c sets internal fl
2f8d0 61 67 73 2c 20 62 75 74 20 74 68 65 20 5b 42 45 ags, but the [BE
2f8e0 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 GIN|BEGIN IMMEDI
2f8f0 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 ATE] and.** [BEG
2f900 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c 55 53 49 IN|BEGIN EXCLUSI
2f910 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 VE] commands do
2f920 74 6f 75 63 68 20 74 68 65 20 64 61 74 61 62 61 touch the databa
2f930 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c se and so.** sql
2f940 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
2f950 6c 79 28 29 20 72 65 74 75 72 6e 73 20 66 61 6c ly() returns fal
2f960 73 65 20 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d se for those com
2f970 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 mands..*/.int sq
2f980 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f lite3_stmt_reado
2f990 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 nly(sqlite3_stmt
2f9a0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
2f9b0 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 CAPI3REF: Query
2f9c0 20 54 68 65 20 45 58 50 4c 41 49 4e 20 53 65 74 The EXPLAIN Set
2f9d0 74 69 6e 67 20 46 6f 72 20 41 20 50 72 65 70 61 ting For A Prepa
2f9e0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a red Statement.**
2f9f0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
2fa00 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 _stmt.**.** ^The
2fa10 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 69 73 sqlite3_stmt_is
2fa20 65 78 70 6c 61 69 6e 28 53 29 20 69 6e 74 65 72 explain(S) inter
2fa30 66 61 63 65 20 72 65 74 75 72 6e 73 20 31 20 69 face returns 1 i
2fa40 66 20 74 68 65 0a 2a 2a 20 70 72 65 70 61 72 65 f the.** prepare
2fa50 64 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 d statement S is
2fa60 20 61 6e 20 45 58 50 4c 41 49 4e 20 73 74 61 74 an EXPLAIN stat
2fa70 65 6d 65 6e 74 2c 20 6f 72 20 32 20 69 66 20 74 ement, or 2 if t
2fa80 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 he.** statement
2fa90 53 20 69 73 20 61 6e 20 45 58 50 4c 41 49 4e 20 S is an EXPLAIN
2faa0 51 55 45 52 59 20 50 4c 41 4e 2e 0a 2a 2a 20 5e QUERY PLAN..** ^
2fab0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 The sqlite3_stmt
2fac0 5f 69 73 65 78 70 6c 61 69 6e 28 53 29 20 69 6e _isexplain(S) in
2fad0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2fae0 30 20 69 66 20 53 20 69 73 0a 2a 2a 20 61 6e 20 0 if S is.** an
2faf0 6f 72 64 69 6e 61 72 79 20 73 74 61 74 65 6d 65 ordinary stateme
2fb00 6e 74 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 nt or a NULL poi
2fb10 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c nter..*/.int sql
2fb20 69 74 65 33 5f 73 74 6d 74 5f 69 73 65 78 70 6c ite3_stmt_isexpl
2fb30 61 69 6e 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ain(sqlite3_stmt
2fb40 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
2fb50 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 CAPI3REF: Deter
2fb60 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 mine If A Prepar
2fb70 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 ed Statement Has
2fb80 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d Been Reset.** M
2fb90 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
2fba0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 tmt.**.** ^The s
2fbb0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 qlite3_stmt_busy
2fbc0 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (S) interface re
2fbd0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d turns true (non-
2fbe0 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 zero) if the.**
2fbf0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2fc00 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 ent] S has been
2fc10 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 stepped at least
2fc20 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 once using .**
2fc30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
2fc40 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 ] but has neithe
2fc50 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 r run to complet
2fc60 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a ion (returned.**
2fc70 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 [SQLITE_DONE] f
2fc80 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 rom [sqlite3_ste
2fc90 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 p(S)]) nor.** be
2fca0 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b en reset using [
2fcb0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
2fcc0 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 ]. ^The sqlite3
2fcd0 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a _stmt_busy(S).**
2fce0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2fcf0 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 ns false if S is
2fd00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
2fd10 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 If S is not a
2fd20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 .** NULL pointer
2fd30 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f and is not a po
2fd40 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 inter to a valid
2fd50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2fd60 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c ment].** object,
2fd70 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
2fd80 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 or is undefined
2fd90 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 and probably und
2fda0 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 esirable..**.**
2fdb0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 This interface c
2fdc0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f an be used in co
2fdd0 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 mbination [sqlit
2fde0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a e3_next_stmt()].
2fdf0 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c ** to locate all
2fe00 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2fe10 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 ents associated
2fe20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 with a database
2fe30 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 .** connection t
2fe40 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 hat are in need
2fe50 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 of being reset.
2fe60 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 This can be use
2fe70 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c d,.** for exampl
2fe80 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 e, in diagnostic
2fe90 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 routines to sea
2fea0 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 rch for prepared
2feb0 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 .** statements
2fec0 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 that are holding
2fed0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f a transaction o
2fee0 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 pen..*/.int sqli
2fef0 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 te3_stmt_busy(sq
2ff00 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
2ff10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
2ff20 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 ynamically Typed
2ff30 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a Value Object.**
2ff40 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 KEYWORDS: {prot
2ff50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2ff60 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 lue} {unprotecte
2ff70 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d d sqlite3_value}
2ff80 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 .**.** SQLite us
2ff90 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 es the sqlite3_v
2ffa0 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 alue object to r
2ffb0 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c epresent all val
2ffc0 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 ues.** that can
2ffd0 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 be stored in a d
2ffe0 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 atabase table. S
2fff0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d QLite uses dynam
30000 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 ic typing.** for
30010 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 the values it s
30020 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 tores. ^Values
30030 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 stored in sqlite
30040 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 3_value objects.
30050 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 ** can be intege
30060 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 rs, floating poi
30070 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e nt values, strin
30080 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 gs, BLOBs, or NU
30090 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c LL..**.** An sql
300a0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
300b0 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 t may be either
300c0 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 "protected" or "
300d0 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a unprotected"..**
300e0 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 Some interfaces
300f0 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 require a prote
30100 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
30110 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 ue. Other inter
30120 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 faces.** will ac
30130 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 cept either a pr
30140 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e otected or an un
30150 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
30160 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 3_value..** Ever
30170 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 y interface that
30180 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 accepts sqlite3
30190 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 _value arguments
301a0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 specifies.** wh
301b0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 ether or not it
301c0 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 requires a prote
301d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
301e0 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c ue. The.** [sql
301f0 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 ite3_value_dup()
30200 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 ] interface can
30210 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 be used to const
30220 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 ruct a new .** p
30230 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
30240 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 _value from an u
30250 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
30260 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 e3_value..**.**
30270 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 The terms "prote
30280 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f cted" and "unpro
30290 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f tected" refer to
302a0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a whether or not.
302b0 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 ** a mutex is he
302c0 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c ld. An internal
302d0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 mutex is held f
302e0 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a or a protected.*
302f0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
30300 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 object but no mu
30310 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 tex is held for
30320 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a an unprotected.*
30330 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
30340 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 object. If SQLi
30350 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 te is compiled t
30360 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 o be single-thre
30370 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 aded.** (with [S
30380 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
30390 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 =0] and with [sq
303a0 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
303b0 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 ()] returning 0)
303c0 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 .** or if SQLite
303d0 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f is run in one o
303e0 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 f reduced mutex
303f0 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 modes .** [SQLIT
30400 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
30410 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 HREAD] or [SQLIT
30420 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
30430 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 READ].** then th
30440 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e ere is no distin
30450 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 ction between pr
30460 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 otected and unpr
30470 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
30480 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
30490 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 and they can be
304a0 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 used interchang
304b0 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c eably. However,
304c0 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 .** for maximum
304d0 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 code portability
304e0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 it is recommend
304f0 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 ed that applicat
30500 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 ions.** still ma
30510 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 ke the distincti
30520 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 on between prote
30530 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 cted and unprote
30540 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
30550 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 value objects ev
30560 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 en when not stri
30570 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a ctly required..*
30580 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
30590 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
305a0 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 that are passed
305b0 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e as parameters in
305c0 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d to the.** implem
305d0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 entation of [app
305e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
305f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 SQL functions]
30600 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a are protected..*
30610 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 * ^The sqlite3_v
30620 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 alue object retu
30630 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 rned by.** [sqli
30640 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
30650 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 ()] is unprotect
30660 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 ed..** Unprotect
30670 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
30680 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c objects may onl
30690 79 20 62 65 20 75 73 65 64 20 61 73 20 61 72 67 y be used as arg
306a0 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 5b 73 71 uments.** to [sq
306b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
306c0 75 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ue()], [sqlite3_
306d0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2c 20 61 bind_value()], a
306e0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 nd.** [sqlite3_v
306f0 61 6c 75 65 5f 64 75 70 28 29 5d 2e 0a 2a 2a 20 alue_dup()]..**
30700 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c The [sqlite3_val
30710 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 ue_blob | sqlite
30720 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 3_value_type()]
30730 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 family of.** int
30740 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 erfaces require
30750 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
30760 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 3_value objects.
30770 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
30780 63 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ct sqlite3_value
30790 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a sqlite3_value;.
307a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
307b0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f SQL Function Co
307c0 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a ntext Object.**.
307d0 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 ** The context i
307e0 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 n which an SQL f
307f0 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 unction executes
30800 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e is stored in an
30810 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 .** sqlite3_cont
30820 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 ext object. ^A
30830 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 pointer to an sq
30840 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 lite3_context ob
30850 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 ject.** is alway
30860 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 s first paramete
30870 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f r to [applicatio
30880 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
30890 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 nctions]..** The
308a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
308b0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
308c0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
308d0 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a will pass this.
308e0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 ** pointer throu
308f0 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f gh into calls to
30900 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
30910 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 _int | sqlite3_r
30920 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 esult()],.** [sq
30930 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
30940 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c context()], [sql
30950 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 ite3_user_data()
30960 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 ],.** [sqlite3_c
30970 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 ontext_db_handle
30980 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 ()], [sqlite3_ge
30990 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a t_auxdata()],.**
309a0 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 and/or [sqlite3
309b0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e _set_auxdata()].
309c0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
309d0 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ct sqlite3_conte
309e0 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 xt sqlite3_conte
309f0 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 xt;../*.** CAPI3
30a00 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c REF: Binding Val
30a10 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 ues To Prepared
30a20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 Statements.** KE
30a30 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 YWORDS: {host pa
30a40 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 rameter} {host p
30a50 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 arameters} {host
30a60 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d parameter name}
30a70 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 .** KEYWORDS: {S
30a80 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 QL parameter} {S
30a90 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b QL parameters} {
30aa0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e parameter bindin
30ab0 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 g}.** METHOD: sq
30ac0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
30ad0 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 ^(In the SQL st
30ae0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 atement text inp
30af0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 ut to [sqlite3_p
30b00 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
30b10 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a its variants,.*
30b20 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 * literals may b
30b30 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 e replaced by a
30b40 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 [parameter] that
30b50 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 matches one of
30b60 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d following.** tem
30b70 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 plates:.**.** <u
30b80 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a l>.** <li> ?.**
30b90 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c <li> ?NNN.** <
30ba0 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 li> :VVV.** <li
30bb0 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 > @VVV.** <li>
30bc0 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a $VVV.** </ul>.*
30bd0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 *.** In the temp
30be0 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e lates above, NNN
30bf0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 represents an i
30c00 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a nteger literal,.
30c10 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 ** and VVV repre
30c20 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 sents an alphanu
30c30 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 meric identifier
30c40 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 .)^ ^The values
30c50 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 of these.** par
30c60 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 ameters (also ca
30c70 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d lled "host param
30c80 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 eter names" or "
30c90 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 SQL parameters")
30ca0 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 .** can be set u
30cb0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 sing the sqlite3
30cc0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
30cd0 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e es defined here.
30ce0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
30cf0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
30d00 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
30d10 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 () routines is a
30d20 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 lways.** a point
30d30 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 er to the [sqlit
30d40 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 e3_stmt] object
30d50 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a returned from.**
30d60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
30d70 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 e_v2()] or its v
30d80 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e ariants..**.** ^
30d90 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
30da0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 ent is the index
30db0 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 of the SQL para
30dc0 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e meter to be set.
30dd0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 .** ^The leftmos
30de0 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 t SQL parameter
30df0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 has an index of
30e00 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 1. ^When the sa
30e10 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 me named.** SQL
30e20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 parameter is use
30e30 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 d more than once
30e40 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 , second and sub
30e50 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 sequent.** occur
30e60 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 rences have the
30e70 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 same index as th
30e80 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e e first occurren
30e90 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 ce..** ^The inde
30ea0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 x for named para
30eb0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f meters can be lo
30ec0 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 oked up using th
30ed0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 e.** [sqlite3_bi
30ee0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
30ef0 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 ex()] API if des
30f00 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 ired. ^The inde
30f10 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 x.** for "?NNN"
30f20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 parameters is th
30f30 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a e value of NNN..
30f40 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 ** ^The NNN valu
30f50 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 e must be betwee
30f60 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c n 1 and the [sql
30f70 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a ite3_limit()].**
30f80 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 parameter [SQLI
30f90 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c TE_LIMIT_VARIABL
30fa0 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 E_NUMBER] (defau
30fb0 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a lt value: 999)..
30fc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 **.** ^The third
30fd0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
30fe0 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 value to bind t
30ff0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e o the parameter.
31000 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 .** ^If the thir
31010 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
31020 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
31030 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 () or sqlite3_bi
31040 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f nd_text16().** o
31050 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 r sqlite3_bind_b
31060 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 lob() is a NULL
31070 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 pointer then the
31080 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
31090 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 r.** is ignored
310a0 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 and the end resu
310b0 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 lt is the same a
310c0 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e s sqlite3_bind_n
310d0 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 ull()..**.** ^(I
310e0 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 n those routines
310f0 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 that have a fou
31100 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 rth argument, it
31110 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a s value is the.*
31120 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 * number of byte
31130 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 s in the paramet
31140 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 er. To be clear
31150 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 : the value is t
31160 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
31170 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 <u>bytes</u> in
31180 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 the value, not t
31190 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 he number of cha
311a0 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 racters.)^.** ^I
311b0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
311c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
311d0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 3_bind_text() or
311e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
311f0 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 xt16().** is neg
31200 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 ative, then the
31210 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 length of the st
31220 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e ring is.** the n
31230 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 umber of bytes u
31240 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a p to the first z
31250 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a ero terminator..
31260 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 ** If the fourth
31270 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
31280 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 lite3_bind_blob(
31290 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 ) is negative, t
312a0 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 hen.** the behav
312b0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
312c0 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 ..** If a non-ne
312d0 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 gative fourth pa
312e0 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 rameter is provi
312f0 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ded to sqlite3_b
31300 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 ind_text().** or
31310 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
31320 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 xt16() or sqlite
31330 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 3_bind_text64()
31340 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 then.** that par
31350 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 ameter must be t
31360 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a he byte offset.*
31370 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 * where the NUL
31380 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 terminator would
31390 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 occur assuming
313a0 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 the string were
313b0 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 NUL.** terminate
313c0 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 d. If any NUL c
313d0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 haracters occur
313e0 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 at byte offsets
313f0 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 less than .** th
31400 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 e value of the f
31410 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
31420 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 then the resulti
31430 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 ng string value
31440 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 will.** contain
31450 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 embedded NULs.
31460 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 The result of ex
31470 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 pressions involv
31480 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 ing strings.** w
31490 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c ith embedded NUL
314a0 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a s is undefined..
314b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 **.** ^The fifth
314c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
314d0 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 BLOB and string
314e0 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 binding interfa
314f0 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 ces.** is a dest
31500 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 ructor used to d
31510 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c ispose of the BL
31520 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 OB or.** string
31530 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 after SQLite has
31540 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 finished with i
31550 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 t. ^The destruc
31560 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a tor is called.**
31570 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 to dispose of t
31580 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e he BLOB or strin
31590 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 g even if the ca
315a0 6c 6c 20 74 6f 20 74 68 65 20 62 69 6e 64 20 41 ll to the bind A
315b0 50 49 20 66 61 69 6c 73 2c 0a 2a 2a 20 65 78 63 PI fails,.** exc
315c0 65 70 74 20 74 68 65 20 64 65 73 74 72 75 63 74 ept the destruct
315d0 6f 72 20 69 73 20 6e 6f 74 20 63 61 6c 6c 65 64 or is not called
315e0 20 69 66 20 74 68 65 20 74 68 69 72 64 20 70 61 if the third pa
315f0 72 61 6d 65 74 65 72 20 69 73 20 61 20 4e 55 4c rameter is a NUL
31600 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 L.** pointer or
31610 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
31620 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 eter is negative
31630 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 ..** ^If the fif
31640 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a th argument is.*
31650 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 * the special va
31660 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 lue [SQLITE_STAT
31670 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 IC], then SQLite
31680 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 assumes that th
31690 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e e.** information
316a0 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 is in static, u
316b0 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 nmanaged space a
316c0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 nd does not need
316d0 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a to be freed..**
316e0 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 ^If the fifth a
316f0 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 rgument has the
31700 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 value [SQLITE_TR
31710 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a ANSIENT], then.*
31720 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 * SQLite makes i
31730 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 ts own private c
31740 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 opy of the data
31750 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 immediately, bef
31760 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 ore.** the sqlit
31770 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
31780 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a ine returns..**.
31790 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 ** ^The sixth ar
317a0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
317b0 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 3_bind_text64()
317c0 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a must be one of.*
317d0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c * [SQLITE_UTF8],
317e0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c [SQLITE_UTF16],
317f0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 [SQLITE_UTF16BE
31800 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 ], or [SQLITE_UT
31810 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 F16LE].** to spe
31820 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e cify the encodin
31830 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e g of the text in
31840 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
31850 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 eter. If.** the
31860 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 sixth argument
31870 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f to sqlite3_bind_
31880 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 text64() is not
31890 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c one of the.** al
318a0 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f lowed values sho
318b0 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 wn above, or if
318c0 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e the text encodin
318d0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a g is different.*
318e0 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 * from the encod
318f0 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79 ing specified by
31900 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d the sixth param
31910 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 eter, then the b
31920 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e ehavior.** is un
31930 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e defined..**.** ^
31940 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 The sqlite3_bind
31950 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 _zeroblob() rout
31960 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 ine binds a BLOB
31970 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 of length N tha
31980 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 t.** is filled w
31990 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 ith zeroes. ^A
319a0 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 zeroblob uses a
319b0 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 fixed amount of
319c0 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 memory.** (just
319d0 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f an integer to ho
319e0 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 ld its size) whi
319f0 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 le it is being p
31a00 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 rocessed..** Zer
31a10 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e oblobs are inten
31a20 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 ded to serve as
31a30 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 placeholders for
31a40 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 BLOBs whose.**
31a50 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 content is later
31a60 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a written using.*
31a70 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f * [sqlite3_blob_
31a80 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 open | increment
31a90 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 al BLOB I/O] rou
31aa0 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 tines..** ^A neg
31ab0 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 ative value for
31ac0 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 the zeroblob res
31ad0 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c ults in a zero-l
31ae0 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a ength BLOB..**.*
31af0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 * ^The sqlite3_b
31b00 69 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c ind_pointer(S,I,
31b10 50 2c 54 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 P,T,D) routine c
31b20 61 75 73 65 73 20 74 68 65 20 49 2d 74 68 20 70 auses the I-th p
31b30 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 5b arameter in.** [
31b40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
31b50 6e 74 5d 20 53 20 74 6f 20 68 61 76 65 20 61 6e nt] S to have an
31b60 20 53 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e 55 SQL value of NU
31b70 4c 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f 20 LL, but to also
31b80 62 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 be.** associated
31b90 20 77 69 74 68 20 74 68 65 20 70 6f 69 6e 74 65 with the pointe
31ba0 72 20 50 20 6f 66 20 74 79 70 65 20 54 2e 20 20 r P of type T.
31bb0 5e 44 20 69 73 20 65 69 74 68 65 72 20 61 20 4e ^D is either a N
31bc0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 0a 2a ULL pointer or.*
31bd0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * a pointer to a
31be0 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 destructor func
31bf0 74 69 6f 6e 20 66 6f 72 20 50 2e 20 5e 53 51 4c tion for P. ^SQL
31c00 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 ite will invoke
31c10 74 68 65 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f the.** destructo
31c20 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c r D with a singl
31c30 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 50 20 e argument of P
31c40 77 68 65 6e 20 69 74 20 69 73 20 66 69 6e 69 73 when it is finis
31c50 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 50 2e 20 hed using.** P.
31c60 20 54 68 65 20 54 20 70 61 72 61 6d 65 74 65 72 The T parameter
31c70 20 73 68 6f 75 6c 64 20 62 65 20 61 20 73 74 61 should be a sta
31c80 74 69 63 20 73 74 72 69 6e 67 2c 20 70 72 65 66 tic string, pref
31c90 65 72 61 62 6c 79 20 61 20 73 74 72 69 6e 67 0a erably a string.
31ca0 2a 2a 20 6c 69 74 65 72 61 6c 2e 20 54 68 65 20 ** literal. The
31cb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 sqlite3_bind_poi
31cc0 6e 74 65 72 28 29 20 72 6f 75 74 69 6e 65 20 69 nter() routine i
31cd0 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a s part of the.**
31ce0 20 5b 70 6f 69 6e 74 65 72 20 70 61 73 73 69 6e [pointer passin
31cf0 67 20 69 6e 74 65 72 66 61 63 65 5d 20 61 64 64 g interface] add
31d00 65 64 20 66 6f 72 20 53 51 4c 69 74 65 20 33 2e ed for SQLite 3.
31d10 32 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 20.0..**.** ^If
31d20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 any of the sqlit
31d30 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
31d40 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
31d50 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e with a NULL poin
31d60 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b ter.** for the [
31d70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
31d80 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 nt] or with a pr
31d90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
31da0 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 for which.** [s
31db0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 qlite3_step()] h
31dc0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d as been called m
31dd0 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 ore recently tha
31de0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 n [sqlite3_reset
31df0 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ()],.** then the
31e00 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 call will retur
31e10 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 n [SQLITE_MISUSE
31e20 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 ]. If any sqlit
31e30 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f e3_bind_().** ro
31e40 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 utine is passed
31e50 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
31e60 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 ement] that has
31e70 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 been finalized,
31e80 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 the.** result is
31e90 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 undefined and p
31ea0 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e robably harmful.
31eb0 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 .**.** ^Bindings
31ec0 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 are not cleared
31ed0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 by the [sqlite3
31ee0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e _reset()] routin
31ef0 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 e..** ^Unbound p
31f00 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e arameters are in
31f10 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c terpreted as NUL
31f20 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 L..**.** ^The sq
31f30 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 lite3_bind_* rou
31f40 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 tines return [SQ
31f50 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
31f60 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 ess or an.** [er
31f70 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 ror code] if any
31f80 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 thing goes wrong
31f90 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f ..** ^[SQLITE_TO
31fa0 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 OBIG] might be r
31fb0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 eturned if the s
31fc0 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 ize of a string
31fd0 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 or BLOB.** excee
31fe0 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 ds limits impose
31ff0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 d by [sqlite3_li
32000 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d mit]([SQLITE_LIM
32010 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a IT_LENGTH]) or.*
32020 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 * [SQLITE_MAX_LE
32030 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 NGTH]..** ^[SQLI
32040 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 TE_RANGE] is ret
32050 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 urned if the par
32060 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 ameter.** index
32070 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e is out of range.
32080 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d ^[SQLITE_NOMEM
32090 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 ] is returned if
320a0 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e malloc() fails.
320b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
320c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
320d0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 arameter_count()
320e0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
320f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
32100 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 me()], and [sqli
32110 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
32120 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a er_index()]..*/.
32130 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
32140 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 _blob(sqlite3_st
32150 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
32160 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f void*, int n, vo
32170 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 id(*)(void*));.i
32180 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
32190 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 blob64(sqlite3_s
321a0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
321b0 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f void*, sqlite3_
321c0 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 uint64,.
321d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
321e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
321f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
32200 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 d_double(sqlite3
32210 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 _stmt*, int, dou
32220 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ble);.int sqlite
32230 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 3_bind_int(sqlit
32240 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 e3_stmt*, int, i
32250 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 nt);.int sqlite3
32260 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 _bind_int64(sqli
32270 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
32280 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
32290 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
322a0 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 _null(sqlite3_st
322b0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 mt*, int);.int s
322c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
322d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
322e0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 nt,const char*,i
322f0 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a nt,void(*)(void*
32300 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f ));.int sqlite3_
32310 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 bind_text16(sqli
32320 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
32330 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
32340 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
32350 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
32360 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 ind_text64(sqlit
32370 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
32380 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 onst char*, sqli
32390 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 te3_uint64,.
323a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
323b0 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 void(*)(voi
323c0 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 d*), unsigned ch
323d0 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e ar encoding);.in
323e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 t sqlite3_bind_v
323f0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d alue(sqlite3_stm
32400 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 t*, int, const s
32410 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
32420 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
32430 5f 70 6f 69 6e 74 65 72 28 73 71 6c 69 74 65 33 _pointer(sqlite3
32440 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 _stmt*, int, voi
32450 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c d*, const char*,
32460 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
32470 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
32480 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 d_zeroblob(sqlit
32490 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 e3_stmt*, int, i
324a0 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 nt n);.int sqlit
324b0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 e3_bind_zeroblob
324c0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 64(sqlite3_stmt*
324d0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 , int, sqlite3_u
324e0 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int64);../*.** C
324f0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
32500 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 Of SQL Parameter
32510 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
32520 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
32530 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 ^This routine ca
32540 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e n be used to fin
32550 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
32560 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d [SQL parameters]
32570 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 .** in a [prepar
32580 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 ed statement].
32590 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 SQL parameters a
325a0 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 re tokens of the
325b0 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f .** form "?", "?
325c0 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 NNN", ":AAA", "$
325d0 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 AAA", or "@AAA"
325e0 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a that serve as.**
325f0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f placeholders fo
32600 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 r values that ar
32610 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
32620 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a blob | bound].**
32630 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 to the paramete
32640 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 rs at a later ti
32650 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 me..**.** ^(This
32660 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c routine actuall
32670 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e y returns the in
32680 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 dex of the large
32690 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a st (rightmost).*
326a0 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 * parameter. For
326b0 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 all forms excep
326c0 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c t ?NNN, this wil
326d0 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 l correspond to
326e0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
326f0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 unique paramete
32700 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 rs. If paramete
32710 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 rs of the ?NNN f
32720 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a orm are used,.**
32730 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 there may be ga
32740 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 ps in the list.)
32750 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ^.**.** See also
32760 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
32770 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
32780 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
32790 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
327a0 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a _name()], and.**
327b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
327c0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
327d0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
327e0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
327f0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 _count(sqlite3_s
32800 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
32810 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 PI3REF: Name Of
32820 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 A Host Parameter
32830 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
32840 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
32850 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 The sqlite3_bind
32860 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
32870 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 P,N) interface r
32880 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 eturns.** the na
32890 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b me of the N-th [
328a0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 SQL parameter] i
328b0 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 n the [prepared
328c0 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a statement] P..**
328d0 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 ^(SQL parameter
328e0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f s of the form "?
328f0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f NNN" or ":AAA" o
32900 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 r "@AAA" or "$AA
32910 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d A".** have a nam
32920 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 e which is the s
32930 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 tring "?NNN" or
32940 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 ":AAA" or "@AAA"
32950 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 or "$AAA".** re
32960 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 spectively..** I
32970 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
32980 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f he initial ":" o
32990 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 r "$" or "@" or
329a0 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 "?".** is includ
329b0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 ed as part of th
329c0 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 e name.)^.** ^Pa
329d0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 rameters of the
329e0 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 form "?" without
329f0 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 a following int
32a00 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d eger have no nam
32a10 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 e.** and are ref
32a20 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d erred to as "nam
32a30 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 eless" or "anony
32a40 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 mous parameters"
32a50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
32a60 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 st host paramete
32a70 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f r has an index o
32a80 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a f 1, not 0..**.*
32a90 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 * ^If the value
32aa0 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 N is out of rang
32ab0 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 e or if the N-th
32ac0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a parameter is.**
32ad0 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 nameless, then
32ae0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 NULL is returned
32af0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 . ^The returned
32b00 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c string is.** al
32b10 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e ways in UTF-8 en
32b20 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 coding even if t
32b30 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 he named paramet
32b40 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e er was.** origin
32b50 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 ally specified a
32b60 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c s UTF-16 in [sql
32b70 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
32b80 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 ],.** [sqlite3_p
32b90 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 repare16_v2()],
32ba0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
32bb0 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a are16_v3()]..**.
32bc0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
32bd0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
32be0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
32bf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
32c00 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
32c10 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 t()], and.** [sq
32c20 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
32c30 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a eter_index()]..*
32c40 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
32c50 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
32c60 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 eter_name(sqlite
32c70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 3_stmt*, int);..
32c80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
32c90 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d Index Of A Param
32ca0 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 eter With A Give
32cb0 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 n Name.** METHOD
32cc0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
32cd0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 *.** ^Return the
32ce0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c index of an SQL
32cf0 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e parameter given
32d00 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 its name. ^The
32d10 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 .** index value
32d20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 returned is suit
32d30 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 able for use as
32d40 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 the second.** pa
32d50 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
32d60 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
32d70 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 lite3_bind()].
32d80 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 ^A zero.** is re
32d90 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 turned if no mat
32da0 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 ching parameter
32db0 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 is found. ^The
32dc0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d parameter.** nam
32dd0 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 e must be given
32de0 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 in UTF-8 even if
32df0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 the original st
32e00 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 atement.** was p
32e10 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 repared from UTF
32e20 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b -16 text using [
32e30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
32e40 36 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 6_v2()] or.** [s
32e50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
32e60 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 _v3()]..**.** Se
32e70 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
32e80 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
32e90 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
32ea0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
32eb0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
32ec0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
32ed0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
32ee0 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 name()]..*/.int
32ef0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
32f00 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c ameter_index(sql
32f10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 ite3_stmt*, cons
32f20 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a t char *zName);.
32f30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
32f40 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 Reset All Bindi
32f50 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 ngs On A Prepare
32f60 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d d Statement.** M
32f70 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
32f80 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 tmt.**.** ^Contr
32f90 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 ary to the intui
32fa0 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 tion of many, [s
32fb0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
32fc0 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a does not reset.*
32fd0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 * the [sqlite3_b
32fe0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 ind_blob | bindi
32ff0 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 ngs] on a [prepa
33000 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
33010 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 ** ^Use this rou
33020 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c tine to reset al
33030 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 l host parameter
33040 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e s to NULL..*/.in
33050 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f t sqlite3_clear_
33060 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 bindings(sqlite3
33070 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
33080 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
33090 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 Of Columns In A
330a0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d Result Set.** M
330b0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
330c0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 tmt.**.** ^Retur
330d0 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 n the number of
330e0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 columns in the r
330f0 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e esult set return
33100 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 ed by the.** [pr
33110 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
33120 5d 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 ]. ^If this rout
33130 69 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20 74 ine returns 0, t
33140 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a hat means the .*
33150 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
33160 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e ement] returns n
33170 6f 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d o data (for exam
33180 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 ple an [UPDATE])
33190 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a ..** ^However, j
331a0 75 73 74 20 62 65 63 61 75 73 65 20 74 68 69 73 ust because this
331b0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
331c0 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 a positive numb
331d0 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d er does not.** m
331e0 65 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 ean that one or
331f0 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61 74 more rows of dat
33200 61 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e a will be return
33210 65 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 73 ed. ^A SELECT s
33220 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c tatement.** will
33230 20 61 6c 77 61 79 73 20 68 61 76 65 20 61 20 70 always have a p
33240 6f 73 69 74 69 76 65 20 73 71 6c 69 74 65 33 5f ositive sqlite3_
33250 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 column_count() b
33260 75 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 ut depending on
33270 74 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 the.** WHERE cla
33280 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 use constraints
33290 61 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63 6f and the table co
332a0 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 ntent, it might
332b0 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a return no rows..
332c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
332d0 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f [sqlite3_data_co
332e0 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 unt()].*/.int sq
332f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 lite3_column_cou
33300 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 nt(sqlite3_stmt
33310 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
33320 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e CAPI3REF: Column
33330 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 Names In A Resu
33340 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 lt Set.** METHOD
33350 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
33360 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
33370 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 ines return the
33380 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f name assigned to
33390 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f a particular co
333a0 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 lumn.** in the r
333b0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b esult set of a [
333c0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
333d0 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 t. ^The sqlite3
333e0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a _column_name().*
333f0 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 * interface retu
33400 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
33410 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
33420 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a ed UTF-8 string.
33430 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 ** and sqlite3_c
33440 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 olumn_name16() r
33450 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
33460 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 to a zero-termi
33470 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 nated.** UTF-16
33480 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 string. ^The fi
33490 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
334a0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
334b0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 tatement].** tha
334c0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 t implements the
334d0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
334e0 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 ent. ^The second
334f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
33500 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 e.** column numb
33510 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f er. ^The leftmo
33520 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d st column is num
33530 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ber 0..**.** ^Th
33540 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
33550 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c g pointer is val
33560 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 id until either
33570 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
33580 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 atement].** is d
33590 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c estroyed by [sql
335a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
335b0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 or until the st
335c0 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d atement is autom
335d0 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 atically.** repr
335e0 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 epared by the fi
335f0 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c rst call to [sql
33600 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 ite3_step()] for
33610 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 a particular ru
33620 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 n.** or until th
33630 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a e next call to.*
33640 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
33650 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 _name() or sqlit
33660 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
33670 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 () on the same c
33680 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 olumn..**.** ^If
33690 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
336a0 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 ) fails during t
336b0 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 he processing of
336c0 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a either routine.
336d0 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 ** (for example
336e0 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 during a convers
336f0 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 ion from UTF-8 t
33700 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 o UTF-16) then a
33710 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 .** NULL pointer
33720 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
33730 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 .** ^The name of
33740 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e a result column
33750 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
33760 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 the "AS" clause
33770 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c for.** that col
33780 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 umn, if there is
33790 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 an AS clause.
337a0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 If there is no A
337b0 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e S clause.** then
337c0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
337d0 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 column is unspe
337e0 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 cified and may c
337f0 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e hange from.** on
33800 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c e release of SQL
33810 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e ite to the next.
33820 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
33830 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
33840 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
33850 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 *, int N);.const
33860 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
33870 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c olumn_name16(sql
33880 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
33890 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 N);../*.** CAPI3
338a0 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 REF: Source Of D
338b0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 ata In A Query R
338c0 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a esult.** METHOD:
338d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
338e0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
338f0 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 nes provide a me
33900 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 ans to determine
33910 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 the database, t
33920 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 able, and.** tab
33930 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 le column that i
33940 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 s the origin of
33950 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 a particular res
33960 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a ult column in.**
33970 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
33980 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d ent..** ^The nam
33990 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
339a0 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f e or table or co
339b0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 lumn can be retu
339c0 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 rned as.** eithe
339d0 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 r a UTF-8 or UTF
339e0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 -16 string. ^Th
339f0 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 e _database_ rou
33a00 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 tines return.**
33a10 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d the database nam
33a20 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 e, the _table_ r
33a30 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
33a40 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 he table name, a
33a50 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e nd.** the origin
33a60 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 _ routines retur
33a70 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d n the column nam
33a80 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 e..** ^The retur
33a90 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 ned string is va
33aa0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 lid until the [p
33ab0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
33ac0 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a t] is destroyed.
33ad0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ** using [sqlite
33ae0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 3_finalize()] or
33af0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 until the state
33b00 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 ment is automati
33b10 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 cally.** reprepa
33b20 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 red by the first
33b30 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
33b40 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 3_step()] for a
33b50 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a particular run.*
33b60 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 * or until the s
33b70 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 ame information
33b80 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 is requested.**
33b90 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 again in a diffe
33ba0 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a rent encoding..*
33bb0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 *.** ^The names
33bc0 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 returned are the
33bd0 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 original un-ali
33be0 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 ased names of th
33bf0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 e.** database, t
33c00 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e able, and column
33c10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
33c20 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
33c30 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 hese interfaces
33c40 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 is a [prepared s
33c50 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 tatement]..** ^T
33c60 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 hese functions r
33c70 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f eturn informatio
33c80 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 n about the Nth
33c90 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 result column re
33ca0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 turned by.** the
33cb0 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 statement, wher
33cc0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e e N is the secon
33cd0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d d function argum
33ce0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 ent..** ^The lef
33cf0 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 t-most column is
33d00 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 column 0 for th
33d10 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a ese routines..**
33d20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 .** ^If the Nth
33d30 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 column returned
33d40 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 by the statement
33d50 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f is an expressio
33d60 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 n or.** subquery
33d70 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f and is not a co
33d80 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e lumn value, then
33d90 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 all of these fu
33da0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a nctions return.*
33db0 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 * NULL. ^These
33dc0 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c routine might al
33dd0 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 so return NULL i
33de0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
33df0 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f ation error.** o
33e00 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 ccurs. ^Otherwi
33e10 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 se, they return
33e20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
33e30 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
33e40 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 e, table,.** or
33e50 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 column that quer
33e60 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 y result column
33e70 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 was extracted fr
33e80 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 om..**.** ^As wi
33e90 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c th all other SQL
33ea0 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 ite APIs, those
33eb0 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 whose names end
33ec0 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e with "16" return
33ed0 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 .** UTF-16 encod
33ee0 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 ed strings and t
33ef0 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f he other functio
33f00 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e ns return UTF-8.
33f10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 .**.** ^These AP
33f20 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 Is are only avai
33f30 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 lable if the lib
33f40 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 rary was compile
33f50 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 d with the.** [S
33f60 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c QLITE_ENABLE_COL
33f70 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d UMN_METADATA] C-
33f80 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d preprocessor sym
33f90 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 bol..**.** If tw
33fa0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 o or more thread
33fb0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f s call one or mo
33fc0 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 re of these rout
33fd0 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 ines against the
33fe0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 same.** prepare
33ff0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 d statement and
34000 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 column at the sa
34010 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 me time then the
34020 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 results are.**
34030 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
34040 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 If two or more
34050 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 threads call one
34060 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c or more.** [sql
34070 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 ite3_column_data
34080 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 base_name | colu
34090 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 mn metadata inte
340a0 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 rfaces].** for t
340b0 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 he same [prepare
340c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 d statement] and
340d0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a result column.*
340e0 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 * at the same ti
340f0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 me then the resu
34100 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
34110 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 d..*/.const char
34120 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
34130 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 _database_name(s
34140 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
34150 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
34160 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
34170 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 tabase_name16(sq
34180 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
34190 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 ;.const char *sq
341a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 lite3_column_tab
341b0 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f le_name(sqlite3_
341c0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
341d0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
341e0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d column_table_nam
341f0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
34200 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 *,int);.const ch
34210 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
34220 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 mn_origin_name(s
34230 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
34240 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
34250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 qlite3_column_or
34260 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 igin_name16(sqli
34270 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
34280 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
34290 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 Declared Dataty
342a0 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 pe Of A Query Re
342b0 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 sult.** METHOD:
342c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
342d0 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 ** ^(The first p
342e0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 arameter is a [p
342f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
34300 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 t]..** If this s
34310 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 tatement is a [S
34320 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
34330 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c and the Nth col
34340 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 umn of the.** re
34350 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 turned result se
34360 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 t of that [SELEC
34370 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f T] is a table co
34380 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 lumn (not an.**
34390 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 expression or su
343a0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 bquery) then the
343b0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f declared type o
343c0 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 f the table.** c
343d0 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 olumn is returne
343e0 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 d.)^ ^If the Nt
343f0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 h column of the
34400 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e result set is an
34410 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f .** expression o
34420 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e r subquery, then
34430 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
34440 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
34450 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 ^The returned st
34460 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 ring is always U
34470 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a TF-8 encoded..**
34480 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c .** ^(For exampl
34490 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 e, given the dat
344a0 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a abase schema:.**
344b0 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 .** CREATE TABLE
344c0 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b t1(c1 VARIANT);
344d0 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 .**.** and the f
344e0 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 ollowing stateme
344f0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 nt to be compile
34500 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 d:.**.** SELECT
34510 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 c1 + 1, c1 FROM
34520 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 t1;.**.** this r
34530 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 outine would ret
34540 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 urn the string "
34550 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 VARIANT" for the
34560 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a second result.*
34570 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c * column (i==1),
34580 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e and a NULL poin
34590 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 ter for the firs
345a0 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 t result column
345b0 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 (i==0).)^.**.**
345c0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e ^SQLite uses dyn
345d0 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 amic run-time ty
345e0 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 ping. ^So just
345f0 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e because a column
34600 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 .** is declared
34610 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 to contain a par
34620 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 ticular type doe
34630 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 s not mean that
34640 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 the.** data stor
34650 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d ed in that colum
34660 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c n is of the decl
34670 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 ared type. SQLi
34680 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c te is.** strongl
34690 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 y typed, but the
346a0 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d typing is dynam
346b0 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 ic not static.
346c0 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f ^Type.** is asso
346d0 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 ciated with indi
346e0 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e vidual values, n
346f0 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 ot with the cont
34700 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 ainers.** used t
34710 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c o hold those val
34720 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ues..*/.const ch
34730 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
34740 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 mn_decltype(sqli
34750 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
34760 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
34770 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 te3_column_declt
34780 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ype16(sqlite3_st
34790 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a mt*,int);../*.**
347a0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 CAPI3REF: Evalu
347b0 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 ate An SQL State
347c0 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ment.** METHOD:
347d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
347e0 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 ** After a [prep
347f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
34800 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 has been prepare
34810 64 20 75 73 69 6e 67 20 61 6e 79 20 6f 66 0a 2a d using any of.*
34820 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
34830 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 re_v2()], [sqlit
34840 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d e3_prepare_v3()]
34850 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 , [sqlite3_prepa
34860 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f re16_v2()],.** o
34870 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
34880 72 65 31 36 5f 76 33 28 29 5d 20 6f 72 20 6f 6e re16_v3()] or on
34890 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a e of the legacy.
348a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 ** interfaces [s
348b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
348c0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ] or [sqlite3_pr
348d0 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 epare16()], this
348e0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 function.** mus
348f0 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 t be called one
34900 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f or more times to
34910 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 evaluate the st
34920 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 atement..**.** T
34930 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 he details of th
34940 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 e behavior of th
34950 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 e sqlite3_step()
34960 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e interface depen
34970 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 d.** on whether
34980 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 the statement wa
34990 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 s prepared using
349a0 20 74 68 65 20 6e 65 77 65 72 20 22 76 58 22 20 the newer "vX"
349b0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 5b 73 interfaces.** [s
349c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
349d0 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 3()], [sqlite3_p
349e0 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 repare_v2()], [s
349f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
34a00 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 _v3()],.** [sqli
34a10 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
34a20 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 ()] or the older
34a30 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 legacy.** inter
34a40 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 faces [sqlite3_p
34a50 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 repare()] and [s
34a60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
34a70 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 ()]. The use of
34a80 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 58 22 the.** new "vX"
34a90 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 interface is re
34aa0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 commended for ne
34ab0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 w applications b
34ac0 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a ut the legacy.**
34ad0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 interface will
34ae0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 continue to be s
34af0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 upported..**.**
34b00 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 ^In the legacy i
34b10 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 nterface, the re
34b20 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 turn value will
34b30 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 be either [SQLIT
34b40 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c E_BUSY],.** [SQL
34b50 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 ITE_DONE], [SQLI
34b60 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 TE_ROW], [SQLITE
34b70 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c _ERROR], or [SQL
34b80 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 ITE_MISUSE]..**
34b90 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 ^With the "v2" i
34ba0 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 nterface, any of
34bb0 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 the other [resu
34bc0 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 lt codes] or.**
34bd0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
34be0 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 codes] might be
34bf0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c returned as wel
34c00 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 l..**.** ^[SQLIT
34c10 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 E_BUSY] means th
34c20 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 at the database
34c30 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c engine was unabl
34c40 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 e to acquire the
34c50 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 .** database loc
34c60 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 ks it needs to d
34c70 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 o its job. ^If
34c80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
34c90 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f a [COMMIT].** o
34ca0 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 r occurs outside
34cb0 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 of an explicit
34cc0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 transaction, the
34cd0 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 n you can retry
34ce0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 the.** statement
34cf0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d . If the statem
34d00 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f ent is not a [CO
34d10 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 MMIT] and occurs
34d20 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 within an.** ex
34d30 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 plicit transacti
34d40 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 on then you shou
34d50 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 ld rollback the
34d60 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f transaction befo
34d70 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 re.** continuing
34d80 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 ..**.** ^[SQLITE
34d90 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 _DONE] means tha
34da0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 t the statement
34db0 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 has finished exe
34dc0 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 cuting.** succes
34dd0 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 sfully. sqlite3
34de0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e _step() should n
34df0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 ot be called aga
34e00 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 in on this virtu
34e10 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 al.** machine wi
34e20 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c thout first call
34e30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
34e40 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 et()] to reset t
34e50 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 he virtual.** ma
34e60 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 chine back to it
34e70 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e s initial state.
34e80 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 .**.** ^If the S
34e90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 QL statement bei
34ea0 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 ng executed retu
34eb0 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 rns any data, th
34ec0 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a en [SQLITE_ROW].
34ed0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 ** is returned e
34ee0 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 ach time a new r
34ef0 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 ow of data is re
34f00 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 ady for processi
34f10 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c ng by the.** cal
34f20 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 ler. The values
34f30 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 may be accessed
34f40 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d using the [colum
34f50 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f n access functio
34f60 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ns]..** sqlite3_
34f70 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 step() is called
34f80 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 again to retrie
34f90 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 ve the next row
34fa0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e of data..**.** ^
34fb0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d [SQLITE_ERROR] m
34fc0 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d eans that a run-
34fd0 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 time error (such
34fe0 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 as a constraint
34ff0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 .** violation) h
35000 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 as occurred. sq
35010 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f lite3_step() sho
35020 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 uld not be calle
35030 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 d again on.** th
35040 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 e VM. More infor
35050 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f mation may be fo
35060 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b und by calling [
35070 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
35080 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 ]..** ^With the
35090 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
350a0 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 , a more specifi
350b0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f c error code (fo
350c0 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 r example,.** [S
350d0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d QLITE_INTERRUPT]
350e0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 , [SQLITE_SCHEMA
350f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 ], [SQLITE_CORRU
35100 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 PT], and so fort
35110 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 h).** can be obt
35120 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 ained by calling
35130 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
35140 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 )] on the.** [pr
35150 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
35160 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 ]. ^In the "v2"
35170 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 interface,.** t
35180 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 he more specific
35190 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 error code is r
351a0 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 eturned directly
351b0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 by sqlite3_step
351c0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 ()..**.** [SQLIT
351d0 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 E_MISUSE] means
351e0 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f that the this ro
351f0 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 utine was called
35200 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 inappropriately
35210 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 ..** Perhaps it
35220 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 was called on a
35230 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
35240 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a ent] that has.**
35250 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 already been [s
35260 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 qlite3_finalize
35270 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 | finalized] or
35280 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a on one that had.
35290 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 ** previously re
352a0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 turned [SQLITE_E
352b0 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 RROR] or [SQLITE
352c0 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 _DONE]. Or it c
352d0 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 ould.** be the c
352e0 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d ase that the sam
352f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
35300 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 ction is being u
35310 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a sed by two or.**
35320 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 more threads at
35330 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 the same moment
35340 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 in time..**.**
35350 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 For all versions
35360 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f of SQLite up to
35370 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 and including 3
35380 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 .6.23.1, a call
35390 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 to.** [sqlite3_r
353a0 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 eset()] was requ
353b0 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 ired after sqlit
353c0 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e e3_step() return
353d0 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f ed anything.** o
353e0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
353f0 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e E_ROW] before an
35400 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 y subsequent inv
35410 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 ocation of.** sq
35420 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 lite3_step(). F
35430 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 ailure to reset
35440 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 the prepared sta
35450 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a tement using .**
35460 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
35470 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 )] would result
35480 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 in an [SQLITE_MI
35490 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f SUSE] return fro
354a0 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 m.** sqlite3_ste
354b0 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 p(). But after
354c0 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e [version 3.6.23.
354d0 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 1] ([dateof:3.6.
354e0 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 23.1],.** sqlite
354f0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 3_step() began.*
35500 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 * calling [sqlit
35510 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f e3_reset()] auto
35520 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 matically in thi
35530 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 s circumstance r
35540 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 ather.** than re
35550 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f turning [SQLITE_
35560 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 MISUSE]. This i
35570 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 s not considered
35580 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 a compatibility
35590 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 .** break becaus
355a0 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f e any applicatio
355b0 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 n that ever rece
355c0 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d ives an SQLITE_M
355d0 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 ISUSE error.** i
355e0 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 s broken by defi
355f0 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 nition. The [SQ
35600 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 LITE_OMIT_AUTORE
35610 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d SET] compile-tim
35620 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 e option.** can
35630 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f be used to resto
35640 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 re the legacy be
35650 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 havior..**.** <b
35660 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 >Goofy Interface
35670 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 Alert:</b> In t
35680 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
35690 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ace, the sqlite3
356a0 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 _step().** API a
356b0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 lways returns a
356c0 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f generic error co
356d0 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f de, [SQLITE_ERRO
356e0 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e R], following an
356f0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 y.** error other
35700 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 than [SQLITE_BU
35710 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f SY] and [SQLITE_
35720 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 MISUSE]. You mu
35730 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 st call.** [sqli
35740 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
35750 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
35760 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f e()] in order to
35770 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 find one of the
35780 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 .** specific [er
35790 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 ror codes] that
357a0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 better describes
357b0 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 the error..** W
357c0 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 e admit that thi
357d0 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 s is a goofy des
357e0 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 ign. The proble
357f0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 m has been fixed
35800 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 .** with the "v2
35810 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 " interface. If
35820 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c you prepare all
35830 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 of your SQL sta
35840 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 tements.** using
35850 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
35860 65 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71 6c 69 e_v3()] or [sqli
35870 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
35880 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ].** or [sqlite3
35890 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
358a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
358b0 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 73 pare16_v3()] ins
358c0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c tead.** of the l
358d0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 egacy [sqlite3_p
358e0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 repare()] and [s
358f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
35900 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a ()] interfaces,.
35910 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 ** then the more
35920 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 specific [error
35930 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 codes] are retu
35940 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a rned directly.**
35950 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 by sqlite3_step
35960 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 (). The use of
35970 74 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 the "vX" interfa
35980 63 65 73 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 ces is recommend
35990 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ed..*/.int sqlit
359a0 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f e3_step(sqlite3_
359b0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
359c0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
359d0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 of columns in a
359e0 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 result set.** ME
359f0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
35a00 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 mt.**.** ^The sq
35a10 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
35a20 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (P) interface re
35a30 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
35a40 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 of columns in t
35a50 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f he.** current ro
35a60 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 w of the result
35a70 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 set of [prepared
35a80 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a statement] P..*
35a90 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 * ^If prepared s
35aa0 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 tatement P does
35ab0 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 not have results
35ac0 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e ready to return
35ad0 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 .** (via calls t
35ae0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 o the [sqlite3_c
35af0 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 olumn_int | sqli
35b00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 te3_column_*()]
35b10 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 of.** interfaces
35b20 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 ) then sqlite3_d
35b30 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 ata_count(P) ret
35b40 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 urns 0..** ^The
35b50 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
35b60 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c nt(P) routine al
35b70 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 so returns 0 if
35b80 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e P is a NULL poin
35b90 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ter..** ^The sql
35ba0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
35bb0 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 P) routine retur
35bc0 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 ns 0 if the prev
35bd0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 ious call to.**
35be0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 [sqlite3_step](P
35bf0 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 ) returned [SQLI
35c00 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 TE_DONE]. ^The
35c10 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
35c20 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 nt(P).** will re
35c30 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 turn non-zero if
35c40 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 previous call t
35c50 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d o [sqlite3_step]
35c60 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 (P) returned.**
35c70 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 [SQLITE_ROW], ex
35c80 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 cept in the case
35c90 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 of the [PRAGMA
35ca0 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 incremental_vacu
35cb0 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 um].** where it
35cc0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a always returns z
35cd0 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 ero since each s
35ce0 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 tep of that mult
35cf0 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 i-step.** pragma
35d00 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d returns 0 colum
35d10 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a ns of data..**.*
35d20 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
35d30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e ite3_column_coun
35d40 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 t()].*/.int sqli
35d50 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 te3_data_count(s
35d60 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
35d70 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
35d80 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 3REF: Fundamenta
35d90 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b l Datatypes.** K
35da0 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f EYWORDS: SQLITE_
35db0 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 TEXT.**.** ^(Eve
35dc0 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 ry value in SQLi
35dd0 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 te has one of fi
35de0 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 ve fundamental d
35df0 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 atatypes:.**.**
35e00 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d <ul>.** <li> 64-
35e10 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
35e20 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 er.** <li> 64-bi
35e30 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 t IEEE floating
35e40 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 point number.**
35e50 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c <li> string.** <
35e60 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e li> BLOB.** <li>
35e70 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e NULL.** </ul>)^
35e80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
35e90 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 stants are codes
35ea0 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f for each of tho
35eb0 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 se types..**.**
35ec0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 Note that the SQ
35ed0 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 LITE_TEXT consta
35ee0 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 nt was also used
35ef0 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 in SQLite versi
35f00 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f on 2.** for a co
35f10 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 mpletely differe
35f20 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 nt meaning. Sof
35f30 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 tware that links
35f40 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a against both.**
35f50 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
35f60 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 2 and SQLite ver
35f70 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 sion 3 should us
35f80 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 e SQLITE3_TEXT,
35f90 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 not.** SQLITE_TE
35fa0 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 XT..*/.#define S
35fb0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 QLITE_INTEGER 1
35fc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
35fd0 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 FLOAT 2.#defi
35fe0 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 ne SQLITE_BLOB
35ff0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
36000 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 ITE_NULL 5.#
36010 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 ifdef SQLITE_TEX
36020 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 T.# undef SQLITE
36030 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 _TEXT.#else.# de
36040 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 fine SQLITE_TEXT
36050 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 3.#endif.#d
36060 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 efine SQLITE3_TE
36070 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 XT 3../*.**
36080 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 CAPI3REF: Result
36090 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 Values From A Q
360a0 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 uery.** KEYWORDS
360b0 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 : {column access
360c0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d functions}.** M
360d0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
360e0 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d tmt.**.** <b>Sum
360f0 6d 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c mary:</b>.** <bl
36100 6f 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20 ockquote><table
36110 62 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70 61 64 border=0 cellpad
36120 64 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61 63 69 ding=0 cellspaci
36130 6e 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 ng=0>.** <tr><td
36140 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ><b>sqlite3_colu
36150 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 mn_blob</b><td>&
36160 72 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 rarr;<td>BLOB re
36170 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e sult.** <tr><td>
36180 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d <b>sqlite3_colum
36190 6e 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e n_double</b><td>
361a0 26 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c 20 72 →<td>REAL r
361b0 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 esult.** <tr><td
361c0 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ><b>sqlite3_colu
361d0 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 mn_int</b><td>&r
361e0 61 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74 20 49 arr;<td>32-bit I
361f0 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a NTEGER result.**
36200 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 <tr><td><b>sqli
36210 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 te3_column_int64
36220 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 </b><td>→<t
36230 64 3e 36 34 2d 62 69 74 20 49 4e 54 45 47 45 52 d>64-bit INTEGER
36240 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c result.** <tr><
36250 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f td><b>sqlite3_co
36260 6c 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 lumn_text</b><td
36270 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 38 >→<td>UTF-8
36280 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 TEXT result.**
36290 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 <tr><td><b>sqlit
362a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
362b0 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 </b><td>→<t
362c0 64 3e 55 54 46 2d 31 36 20 54 45 58 54 20 72 65 d>UTF-16 TEXT re
362d0 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e sult.** <tr><td>
362e0 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d <b>sqlite3_colum
362f0 6e 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 n_value</b><td>&
36300 72 61 72 72 3b 3c 74 64 3e 54 68 65 20 72 65 73 rarr;<td>The res
36310 75 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 ult as an .** [s
36320 71 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75 6e 70 qlite3_value|unp
36330 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
36340 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a _value] object..
36350 2a 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62 73 70 ** <tr><td> 
36360 3b 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 ;<td> <td>&
36370 6e 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 nbsp;.** <tr><td
36380 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ><b>sqlite3_colu
36390 6d 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74 64 3e mn_bytes</b><td>
363a0 26 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65 20 6f →<td>Size o
363b0 66 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 f a BLOB.** or a
363c0 20 55 54 46 2d 38 20 54 45 58 54 20 72 65 73 75 UTF-8 TEXT resu
363d0 6c 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c lt in bytes.** <
363e0 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 tr><td><b>sqlite
363f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
36400 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e </b>
36410 0a 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b 26 6e .** <td>→&n
36420 62 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e 53 69 bsp; <td>Si
36430 7a 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a 2a 20 ze of UTF-16.**
36440 54 45 58 54 20 69 6e 20 62 79 74 65 73 0a 2a 2a TEXT in bytes.**
36450 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 <tr><td><b>sqli
36460 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c te3_column_type<
36470 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 /b><td>→<td
36480 3e 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61 74 61 >Default.** data
36490 74 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 type of the resu
364a0 6c 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f lt.** </table></
364b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
364c0 2a 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 * <b>Details:</b
364d0 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 >.**.** ^These r
364e0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 outines return i
364f0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 nformation about
36500 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e a single column
36510 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a of the current.
36520 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 ** result row of
36530 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 a query. ^In e
36540 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 very case the fi
36550 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
36560 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 a pointer.** to
36570 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
36580 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 atement] that is
36590 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 being evaluated
365a0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 (the [sqlite3_s
365b0 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 tmt*].** that wa
365c0 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 s returned from
365d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
365e0 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 _v2()] or one of
365f0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a its variants).*
36600 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 * and the second
36610 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
36620 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f index of the co
36630 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 lumn for which i
36640 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 nformation.** sh
36650 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
36660 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 . ^The leftmost
36670 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 column of the re
36680 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 sult set has the
36690 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 index 0..** ^Th
366a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
366b0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c mns in the resul
366c0 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 t can be determi
366d0 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ned using.** [sq
366e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 lite3_column_cou
366f0 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 nt()]..**.** If
36700 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
36710 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 t does not curre
36720 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 ntly point to a
36730 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 valid row, or if
36740 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 the.** column i
36750 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 ndex is out of r
36760 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 ange, the result
36770 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
36780 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
36790 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c may only be cal
367a0 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 led when the mos
367b0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
367c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
367d0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 p()] has returne
367e0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 d [SQLITE_ROW] a
367f0 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 nd neither.** [s
36800 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
36810 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e nor [sqlite3_fin
36820 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 alize()] have be
36830 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 en called subseq
36840 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e uently..** If an
36850 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 y of these routi
36860 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 nes are called a
36870 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 fter [sqlite3_re
36880 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 set()] or.** [sq
36890 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
368a0 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 ] or after [sqli
368b0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
368c0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 returned.** some
368d0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e thing other than
368e0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 [SQLITE_ROW], t
368f0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
36900 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 ndefined..** If
36910 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
36920 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 or [sqlite3_res
36930 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 et()] or [sqlite
36940 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 3_finalize()].**
36950 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d are called from
36960 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 a different thr
36970 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 ead while any of
36980 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a these routines.
36990 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 ** are pending,
369a0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 then the results
369b0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
369c0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
369d0 73 69 78 20 69 6e 74 65 72 66 61 63 65 73 20 28 six interfaces (
369e0 5f 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 _blob, _double,
369f0 5f 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 _int, _int64, _t
36a00 65 78 74 2c 20 61 6e 64 20 5f 74 65 78 74 31 36 ext, and _text16
36a10 29 0a 2a 2a 20 65 61 63 68 20 72 65 74 75 72 6e ).** each return
36a20 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 the value of a
36a30 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e result column in
36a40 20 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61 a specific data
36a50 20 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 format. If.**
36a60 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d the result colum
36a70 6e 20 69 73 20 6e 6f 74 20 69 6e 69 74 69 61 6c n is not initial
36a80 6c 79 20 69 6e 20 74 68 65 20 72 65 71 75 65 73 ly in the reques
36a90 74 65 64 20 66 6f 72 6d 61 74 20 28 66 6f 72 20 ted format (for
36aa0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 example,.** if t
36ab0 68 65 20 71 75 65 72 79 20 72 65 74 75 72 6e 73 he query returns
36ac0 20 61 6e 20 69 6e 74 65 67 65 72 20 62 75 74 20 an integer but
36ad0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 the sqlite3_colu
36ae0 6d 6e 5f 74 65 78 74 28 29 20 69 6e 74 65 72 66 mn_text() interf
36af0 61 63 65 0a 2a 2a 20 69 73 20 75 73 65 64 20 74 ace.** is used t
36b00 6f 20 65 78 74 72 61 63 74 20 74 68 65 20 76 61 o extract the va
36b10 6c 75 65 29 20 74 68 65 6e 20 61 6e 20 61 75 74 lue) then an aut
36b20 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76 omatic type conv
36b30 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 ersion is perfor
36b40 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 med..**.** ^The
36b50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
36b60 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 ype() routine re
36b70 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 turns the.** [SQ
36b80 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 LITE_INTEGER | d
36b90 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f atatype code] fo
36ba0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 r the initial da
36bb0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 ta type.** of th
36bc0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e e result column.
36bd0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 ^The returned
36be0 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 value is one of
36bf0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d [SQLITE_INTEGER]
36c00 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f ,.** [SQLITE_FLO
36c10 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 AT], [SQLITE_TEX
36c20 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 T], [SQLITE_BLOB
36c30 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 ], or [SQLITE_NU
36c40 4c 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 LL]..** The retu
36c50 72 6e 20 76 61 6c 75 65 20 6f 66 20 73 71 6c 69 rn value of sqli
36c60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
36c70 29 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f ) can be used to
36c80 20 64 65 63 69 64 65 20 77 68 69 63 68 0a 2a 2a decide which.**
36c90 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 73 69 of the first si
36ca0 78 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 x interface shou
36cb0 6c 64 20 62 65 20 75 73 65 64 20 74 6f 20 65 78 ld be used to ex
36cc0 74 72 61 63 74 20 74 68 65 20 63 6f 6c 75 6d 6e tract the column
36cd0 20 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 76 value..** The v
36ce0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
36cf0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
36d00 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d type() is only m
36d10 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 0a eaningful if no.
36d20 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70 ** automatic typ
36d30 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 e conversions ha
36d40 76 65 20 6f 63 63 75 72 72 65 64 20 66 6f 72 20 ve occurred for
36d50 74 68 65 20 76 61 6c 75 65 20 69 6e 20 71 75 65 the value in que
36d60 73 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 stion. .** Afte
36d70 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 r a type convers
36d80 69 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c 74 20 ion, the result
36d90 6f 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 of calling sqlit
36da0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
36db0 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 .** is undefined
36dc0 2c 20 74 68 6f 75 67 68 20 68 61 72 6d 6c 65 73 , though harmles
36dd0 73 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 s. Future.** ve
36de0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
36df0 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 may change the
36e00 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 behavior of sqli
36e10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
36e20 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 ).** following a
36e30 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
36e40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 ..**.** If the r
36e50 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 esult is a BLOB
36e60 6f 72 20 61 20 54 45 58 54 20 73 74 72 69 6e 67 or a TEXT string
36e70 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 , then the sqlit
36e80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
36e90 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
36ea0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
36eb0 20 69 6e 74 65 72 66 61 63 65 73 20 63 61 6e 20 interfaces can
36ec0 62 65 20 75 73 65 64 20 74 6f 20 64 65 74 65 72 be used to deter
36ed0 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 0a 2a 2a mine the size.**
36ee0 20 6f 66 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 of that BLOB or
36ef0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e string..**.** ^
36f00 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
36f10 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 a BLOB or UTF-8
36f20 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 string then the
36f30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
36f40 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 bytes().** routi
36f50 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ne returns the n
36f60 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
36f70 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 n that BLOB or s
36f80 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 tring..** ^If th
36f90 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 e result is a UT
36fa0 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 F-16 string, the
36fb0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e n sqlite3_column
36fc0 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 _bytes() convert
36fd0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 s.** the string
36fe0 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 to UTF-8 and the
36ff0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
37000 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a mber of bytes..*
37010 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
37020 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 is a numeric va
37030 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 lue then sqlite3
37040 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
37050 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 uses.** [sqlite3
37060 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 _snprintf()] to
37070 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c convert that val
37080 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 ue to a UTF-8 st
37090 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 ring and returns
370a0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
370b0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 f bytes in that
370c0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
370d0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c he result is NUL
370e0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f L, then sqlite3_
370f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 column_bytes() r
37100 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a eturns zero..**.
37110 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
37120 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 t is a BLOB or U
37130 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 TF-16 string the
37140 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f n the sqlite3_co
37150 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a lumn_bytes16().*
37160 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e * routine return
37170 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
37180 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c bytes in that BL
37190 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a OB or string..**
371a0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
371b0 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e is a UTF-8 strin
371c0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f g, then sqlite3_
371d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
371e0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 converts.** the
371f0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 string to UTF-1
37200 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6 and then retur
37210 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
37220 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 bytes..** ^If t
37230 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e he result is a n
37240 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 umeric value the
37250 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e n sqlite3_column
37260 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a _bytes16() uses.
37270 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 ** [sqlite3_snpr
37280 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 intf()] to conve
37290 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f rt that value to
372a0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 a UTF-16 string
372b0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 and returns.**
372c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
372d0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 tes in that stri
372e0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 ng..** ^If the r
372f0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 esult is NULL, t
37300 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
37310 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 mn_bytes16() ret
37320 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a urns zero..**.**
37330 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 ^The values ret
37340 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
37350 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
37360 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 ] and .** [sqlit
37370 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
37380 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 6()] do not incl
37390 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 ude the zero ter
373a0 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 minators at the
373b0 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 end.** of the st
373c0 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 ring. ^For clar
373d0 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 ity: the values
373e0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
373f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
37400 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c ytes()] and [sql
37410 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
37420 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e s16()] are the n
37430 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 umber of.** byte
37440 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c s in the string,
37450 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 not the number
37460 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a of characters..*
37470 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 *.** ^Strings re
37480 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
37490 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
374a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
374b0 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 mn_text16(),.**
374c0 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e even empty strin
374d0 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a gs, are always z
374e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 ero-terminated.
374f0 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 ^The return.**
37500 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 value from sqlit
37510 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
37520 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 for a zero-leng
37530 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c th BLOB is a NUL
37540 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
37550 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e <b>Warning:</b>
37560 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 ^The object ret
37570 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
37580 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 3_column_value()
37590 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 ] is an.** [unpr
375a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
375b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 value] object.
375c0 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 In a multithread
375d0 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a ed environment,.
375e0 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 ** an unprotecte
375f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
37600 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 object may only
37610 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 be used safely w
37620 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ith.** [sqlite3_
37630 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e bind_value()] an
37640 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c d [sqlite3_resul
37650 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 t_value()]..** I
37660 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 f the [unprotect
37670 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
37680 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 ] object returne
37690 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d by.** [sqlite3
376a0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
376b0 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 is used in any
376c0 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 other way, inclu
376d0 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f ding calls.** to
376e0 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b routines like [
376f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e sqlite3_value_in
37700 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 t()], [sqlite3_v
37710 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a alue_text()],.**
37720 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c or [sqlite3_val
37730 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 ue_bytes()], the
37740 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 behavior is not
37750 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 20 threadsafe..**
37760 48 65 6e 63 65 2c 20 74 68 65 20 73 71 6c 69 74 Hence, the sqlit
37770 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
37780 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 ) interface.** i
37790 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 s normally only
377a0 75 73 65 66 75 6c 20 77 69 74 68 69 6e 20 74 68 useful within th
377b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
377c0 20 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 of .** [applica
377d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
377e0 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 20 5b functions] or [
377f0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2c virtual tables],
37800 20 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a 20 74 not within.** t
37810 6f 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69 63 61 op-level applica
37820 74 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a tion code..**.**
37830 20 54 68 65 20 74 68 65 73 65 20 72 6f 75 74 69 The these routi
37840 6e 65 73 20 6d 61 79 20 61 74 74 65 6d 70 74 20 nes may attempt
37850 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 64 to convert the d
37860 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 atatype of the r
37870 65 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 esult..** ^For e
37880 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 xample, if the i
37890 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e nternal represen
378a0 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 tation is FLOAT
378b0 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c and a text resul
378c0 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 t.** is requeste
378d0 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 d, [sqlite3_snpr
378e0 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 intf()] is used
378f0 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 internally to pe
37900 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e rform the.** con
37910 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 version automati
37920 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f cally. ^(The fo
37930 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 llowing table de
37940 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 tails the conver
37950 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 sions.** that ar
37960 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a e applied:.**.**
37970 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a <blockquote>.**
37980 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 <table border="
37990 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 1">.** <tr><th>
379a0 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 Internal<br>Type
379b0 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c <th> Requested<
379c0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f br>Type <th> Co
379d0 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c nversion.**.** <
379e0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
379f0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
37a00 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 <td> Result is 0
37a10 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
37a20 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 LL <td> FLOA
37a30 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 T <td> Result
37a40 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c is 0.0.** <tr><
37a50 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
37a60 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
37a70 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c Result is a NUL
37a80 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 L pointer.** <tr
37a90 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
37aa0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
37ab0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e d> Result is a N
37ac0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c ULL pointer.** <
37ad0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
37ae0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
37af0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f <td> Convert fro
37b00 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f m integer to flo
37b10 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 at.** <tr><td> I
37b20 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 NTEGER <td> T
37b30 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 EXT <td> ASCI
37b40 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 I rendering of t
37b50 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 he integer.** <t
37b60 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 r><td> INTEGER
37b70 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
37b80 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 td> Same as INTE
37b90 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 GER->TEXT.** <tr
37ba0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c ><td> FLOAT <
37bb0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
37bc0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 d> [CAST] to INT
37bd0 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e EGER.** <tr><td>
37be0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 FLOAT <td>
37bf0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 TEXT <td> AS
37c00 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 CII rendering of
37c10 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 the float.** <t
37c20 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 r><td> FLOAT
37c30 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
37c40 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c td> [CAST] to BL
37c50 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 OB.** <tr><td>
37c60 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 TEXT <td> INT
37c70 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 EGER <td> [CAS
37c80 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a T] to INTEGER.**
37c90 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 <tr><td> TEXT
37ca0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 <td> FLOAT
37cb0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f <td> [CAST] to
37cc0 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 REAL.** <tr><td
37cd0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
37ce0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e BLOB <td> N
37cf0 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e o change.** <tr>
37d00 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 <td> BLOB <t
37d10 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
37d20 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 > [CAST] to INTE
37d30 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 GER.** <tr><td>
37d40 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 BLOB <td> F
37d50 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 LOAT <td> [CA
37d60 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c ST] to REAL.** <
37d70 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 tr><td> BLOB
37d80 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
37d90 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 <td> Add a zero
37da0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 terminator if ne
37db0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e eded.** </table>
37dc0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 .** </blockquote
37dd0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 >)^.**.** Note t
37de0 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f hat when type co
37df0 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c nversions occur,
37e00 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
37e10 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 ed by prior.** c
37e20 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
37e30 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 column_blob(), s
37e40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
37e50 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 xt(), and/or.**
37e60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
37e70 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 ext16() may be i
37e80 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 nvalidated..** T
37e90 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 ype conversions
37ea0 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 and pointer inva
37eb0 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 lidations might
37ec0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 occur.** in the
37ed0 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a following cases:
37ee0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
37ef0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 li> The initial
37f00 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f content is a BLO
37f10 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f B and sqlite3_co
37f20 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a lumn_text() or.*
37f30 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 * sqlite3_c
37f40 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 olumn_text16() i
37f50 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 s called. A zer
37f60 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 o-terminator mig
37f70 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 ht.** need
37f80 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 to be added to t
37f90 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a he string.</li>.
37fa0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 ** <li> The init
37fb0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 ial content is U
37fc0 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 TF-8 text and sq
37fd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
37fe0 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 es16() or.**
37ff0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e sqlite3_column
38000 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c _text16() is cal
38010 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e led. The conten
38020 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 t must be conver
38030 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 ted.** to U
38040 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c TF-16.</li>.** <
38050 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 li> The initial
38060 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 content is UTF-1
38070 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 6 text and sqlit
38080 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
38090 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c ) or.** sql
380a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
380b0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 () is called. T
380c0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 he content must
380d0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 be converted.**
380e0 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f to UTF-8.</
380f0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a li>.** </ul>.**.
38100 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 ** ^Conversions
38110 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 between UTF-16be
38120 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 and UTF-16le ar
38130 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e e always done in
38140 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a place and do.**
38150 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 not invalidate
38160 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c a prior pointer,
38170 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 though of cours
38180 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 e the content of
38190 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 the buffer.** t
381a0 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f hat the prior po
381b0 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 inter references
381c0 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 will have been
381d0 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 modified. Other
381e0 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e kinds.** of con
381f0 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 version are done
38200 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 in place when i
38210 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 t is possible, b
38220 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 ut sometimes the
38230 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 y.** are not pos
38240 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f sible and in tho
38250 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 se cases prior p
38260 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 ointers are inva
38270 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 lidated..**.** T
38280 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 he safest policy
38290 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 is to invoke th
382a0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ese routines.**
382b0 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f in one of the fo
382c0 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a llowing ways:.**
382d0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 .** <ul>.** <li
382e0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
382f0 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 text() followed
38300 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
38310 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a n_bytes()</li>.*
38320 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 * <li>sqlite3_c
38330 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c olumn_blob() fol
38340 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
38350 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c _column_bytes()<
38360 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c /li>.** <li>sql
38370 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
38380 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 16() followed by
38390 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
383a0 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a bytes16()</li>.*
383b0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e * </ul>.**.** In
383c0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f other words, yo
383d0 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 u should call sq
383e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
383f0 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f t(),.** sqlite3_
38400 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f column_blob(), o
38410 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
38420 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 _text16() first
38430 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 to force the res
38440 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 ult.** into the
38450 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 desired format,
38460 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 then invoke sqli
38470 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
38480 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 () or.** sqlite3
38490 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
384a0 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 ) to find the si
384b0 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ze of the result
384c0 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 . Do not mix ca
384d0 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 lls.** to sqlite
384e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
384f0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
38500 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 n_blob() with ca
38510 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 lls to.** sqlite
38520 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
38530 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d (), and do not m
38540 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ix calls to sqli
38550 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
38560 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 6().** with call
38570 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
38580 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a umn_bytes()..**.
38590 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 ** ^The pointers
385a0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 returned are va
385b0 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 lid until a type
385c0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 conversion occu
385d0 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 rs as.** describ
385e0 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 ed above, or unt
385f0 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 il [sqlite3_step
38600 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
38610 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b reset()] or.** [
38620 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
38630 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 ()] is called.
38640 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 ^The memory spac
38650 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 e used to hold s
38660 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c trings.** and BL
38670 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 OBs is freed aut
38680 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 omatically. Do
38690 6e 6f 74 20 70 61 73 73 20 74 68 65 20 70 6f 69 not pass the poi
386a0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a nters returned.*
386b0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
386c0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 column_blob()],
386d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
386e0 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e text()], etc. in
386f0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 to.** [sqlite3_f
38700 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 ree()]..**.** As
38710 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 69 6e 70 long as the inp
38720 75 74 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 ut parameters ar
38730 65 20 63 6f 72 72 65 63 74 2c 20 74 68 65 73 65 e correct, these
3