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 6e 64 69 66 0a 0a 2f nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66 returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 and only if.**
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74 tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e t mutexes. When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72 THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 threadsafe. Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 itted. Without
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 the mutexes, it
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 rs a measurable
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 importance, it
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 texes. But for
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 maximum safety,
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61 ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 rsion of SQLite
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 interface only
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 x setting.** of
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 ADSAFE] flag. I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 xes are enabled
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61 r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 nfig()].** with
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54 the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65 IZED]. ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 ead safety, not
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 ting made by.**
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 threadsafe().**
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 is unchanged by
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 le.** KEYWORDS:
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 tion} {database
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20 ite database is
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 3". It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69 lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20 ts destructors.
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 There are many
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 ces (such as.**
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65 three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 ss-platform way
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 es typedefs for
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 sqlite3_uint64
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 te_uint64 types
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 lite3_int64 and
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 36854775808 and
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 5807 inclusive.
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 te_uint64 types
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35 6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 64_TYPE. typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45 ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20 _UINT64_TYPE.
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73 te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20 e . typedef
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69 e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 _). typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 4;. typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e se. typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 # define double
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 3REF: Closing A
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75 3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75 tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65 ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 t..** ^Calls to
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 sqlite3_close()
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53 e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 QLITE_OK] if.**
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66 ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61 ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61 d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 n is associated
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65 ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20 ).** will leave
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 is called with
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 eallocated when
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 ished. The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72 ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 bage collected,
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 der in which.**
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 destructors are
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 B handles], and
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 s associated.**
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 3] object prior
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 t. ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61 n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 p] objects then
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64 TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 andles],.** and
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 stroyed while a
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 atically rolled
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 back..**.** The
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 ust be either a
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 NULL.** pointer
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 or an [sqlite3]
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 btained.** from
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 d deprecated. I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 r historical.**
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ted..*/.typedef
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 apper around.**
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 e statements of
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 ce runs zero or
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 atements passed
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 context of the
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 tion] passed in
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 gument. ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 is invoked for
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 QL statements.
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e k invocation. ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 e3_exec().** is
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 re skipped. ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 3_free()].** on
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73 arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 ssage string is
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 not NULL and no
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 ng the callback
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 subsequent SQL
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 esult. ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d mn. ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 nter for the.**
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 L pointer. ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 exec() callback
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 rictions:.**.**
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 e 1st parameter
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 ).** is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 t not close the
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 tion] specified
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 by.** the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 modify the SQL
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 assed into.**
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a exec(. sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 tabase */. cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 t char *sql,
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 . int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a r**,char**), /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 on */. void *,
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 /. char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 g
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 Result Codes.**
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 QLite functions
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 SQLITE_OK
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 0 /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 RROR 1
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72 /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 TE_INTERNAL
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 2 /* Internal
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 SQLITE_PERM
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 3 /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nied */.#define
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 SQLITE_ABORT
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 4 /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 _BUSY 5
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 TE_LOCKED
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6 /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 7 /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 TE_READONLY
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 8 /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f TERRUPT 9 /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 OERR 10
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 /* Some kind of
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 T 11 /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 e database disk
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 LITE_NOTFOUND
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 12 /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 ITE_FULL
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 13 /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 ITE_CANTOPEN
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 14 /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 COL 15 /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f PTY 16 /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 QLITE_SCHEMA
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 17 /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 SQLITE_TOOBIG
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 18 /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 CONSTRAINT 19
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 _MISUSE 21
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 NOLFS 22
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a H 23 /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 SQLITE_FORMAT
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20 24 /* Not
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 used */.#define
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 SQLITE_RANGE
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 25 /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 te3_bind out of
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 SQLITE_NOTADB
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 26 /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 opened that is
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 QLITE_NOTICE
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 27 /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a NING 28 /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 OW 100
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 ne SQLITE_DONE
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 101 /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 tions}.**.** In
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 eturn one of 30
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 lt codes]. Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 ver, experience
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 any of.** these
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f ned. They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 t provide as.**
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 about problems
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 ight like. In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33 .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72 .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 ()] API. Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 e extended code
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 for.** the most
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 )]..*/.#define S
5170: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53 QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53 ING_COLLSEQ (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31 QLITE_ERROR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
51b0: 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59 LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c LITE_ERROR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
51f0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 ITE_IOERR_READ
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c ITE_IOERR | (1<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
5240: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 EAD (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 TE_IOERR | (2<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 E_IOERR_WRITE
5280: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 E_IOERR | (3<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 _IOERR_FSYNC
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 _IOERR | (4<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
52f0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 IOERR_DIR_FSYNC
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a IOERR | (5<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5330: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 OERR_TRUNCATE
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 OERR | (6<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5370: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 ERR_FSTAT
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5390: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 ERR | (7<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
53b0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 RR_UNLOCK
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
53d0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 RR | (8<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
53f0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 R_RDLOCK
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
5410: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 R | (9<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5430: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5450: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 | (10<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5470: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 _BLOCKED
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5490: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 | (11<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
54b0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 _NOMEM
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
54d0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 | (12<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
54f0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 _ACCESS
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5510: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 | (13<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5530: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f _CHECKRESERVEDLO
5540: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 CK (SQLITE_IOERR
5550: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 | (14<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5570: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 _LOCK
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5590: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 | (15<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
55b0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 _CLOSE
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
55d0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 | (16<<8)).#def
55e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
55f0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 _DIR_CLOSE
5600: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5610: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 | (17<<8)).#def
5620: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5630: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 _SHMOPEN
5640: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5650: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 | (18<<8)).#def
5660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5670: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 _SHMSIZE
5680: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5690: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 | (19<<8)).#def
56a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
56b0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 _SHMLOCK
56c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
56d0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 | (20<<8)).#def
56e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
56f0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 _SHMMAP
5700: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5710: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 | (21<<8)).#def
5720: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5730: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 _SEEK
5740: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5750: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 | (22<<8)).#def
5760: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5770: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 _DELETE_NOENT
5780: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5790: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 | (23<<8)).#def
57a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
57b0: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 _MMAP
57c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
57d0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 | (24<<8)).#def
57e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
57f0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 _GETTEMPPATH
5800: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5810: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 | (25<<8)).#def
5820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5830: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 _CONVPATH
5840: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5850: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 | (26<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5870: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20 _VNODE
5880: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5890: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 | (27<<8)).#def
58a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
58b0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20 _AUTH
58c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
58d0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66 | (28<<8)).#def
58e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
58f0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20 _BEGIN_ATOMIC
5900: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5910: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66 | (29<<8)).#def
5920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5930: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20 _COMMIT_ATOMIC
5940: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5950: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66 | (30<<8)).#def
5960: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5970: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 _ROLLBACK_ATOMIC
5980: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5990: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66 | (31<<8)).#def
59a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 ine SQLITE_LOCKE
59b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 D_SHAREDCACHE
59c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 (SQLITE_LOCKE
59d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 D | (1<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 fine SQLITE_BUSY
59f0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 _RECOVERY
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 (SQLITE_BUSY
5a10: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 | (1<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
5a30: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 Y_SNAPSHOT
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 (SQLITE_BUS
5a50: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 Y | (2<<8)).#
5a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
5a70: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 NTOPEN_NOTEMPDIR
5a80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 (SQLITE_CA
5a90: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 NTOPEN | (1<<8))
5aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5ab0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 CANTOPEN_ISDIR
5ac0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5ad0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 CANTOPEN | (2<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5af0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 E_CANTOPEN_FULLP
5b00: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 ATH (SQLIT
5b10: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c E_CANTOPEN | (3<
5b20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5b30: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e ITE_CANTOPEN_CON
5b40: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c VPATH (SQL
5b50: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 ITE_CANTOPEN | (
5b60: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 4<<8)).#define S
5b70: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 QLITE_CORRUPT_VT
5b80: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 AB (S
5b90: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 QLITE_CORRUPT |
5ba0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
5bb0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f SQLITE_READONLY_
5bc0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 RECOVERY (
5bd0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 SQLITE_READONLY
5be0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
5bf0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
5c00: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 Y_CANTLOCK
5c10: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c (SQLITE_READONL
5c20: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 Y | (2<<8)).#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f ine SQLITE_READO
5c40: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 NLY_ROLLBACK
5c50: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f (SQLITE_READO
5c60: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 NLY | (3<<8)).#d
5c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
5c80: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 DONLY_DBMOVED
5c90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 (SQLITE_REA
5ca0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a DONLY | (4<<8)).
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
5cc0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e 49 54 EADONLY_CANTINIT
5cd0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 (SQLITE_R
5ce0: 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c 38 29 EADONLY | (5<<8)
5cf0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5d00: 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45 43 54 _READONLY_DIRECT
5d10: 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49 54 45 ORY (SQLITE
5d20: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36 3c 3c _READONLY | (6<<
5d30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5d40: 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 TE_ABORT_ROLLBAC
5d50: 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 K (SQLI
5d60: 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 TE_ABORT | (2<<8
5d70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5d80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 E_CONSTRAINT_CHE
5d90: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 CK (SQLIT
5da0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
5db0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
5dc0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5dd0: 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 _COMMITHOOK (S
5de0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5df0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
5e00: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
5e10: 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 AINT_FOREIGNKEY
5e20: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
5e30: 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 AINT | (3<<8)).#
5e40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
5e50: 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f NSTRAINT_FUNCTIO
5e60: 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f N (SQLITE_CO
5e70: 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 NSTRAINT | (4<<8
5e80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5e90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 E_CONSTRAINT_NOT
5ea0: 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 NULL (SQLIT
5eb0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
5ec0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 5<<8)).#define S
5ed0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5ee0: 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 _PRIMARYKEY (S
5ef0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5f00: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 | (6<<8)).#defi
5f10: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
5f20: 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 AINT_TRIGGER
5f30: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
5f40: 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 AINT | (7<<8)).#
5f50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
5f60: 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 NSTRAINT_UNIQUE
5f70: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
5f80: 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 NSTRAINT | (8<<8
5f90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5fa0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 E_CONSTRAINT_VTA
5fb0: 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 B (SQLIT
5fc0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
5fd0: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 9<<8)).#define S
5fe0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5ff0: 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 _ROWID (S
6000: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
6010: 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 |(10<<8)).#defi
6020: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 ne SQLITE_NOTICE
6030: 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 _RECOVER_WAL
6040: 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 (SQLITE_NOTICE
6050: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
6060: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 ne SQLITE_NOTICE
6070: 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 _RECOVER_ROLLBAC
6080: 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 K (SQLITE_NOTICE
6090: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
60a0: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e ne SQLITE_WARNIN
60b0: 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 G_AUTOINDEX
60c0: 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e (SQLITE_WARNIN
60d0: 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 G | (1<<8)).#def
60e0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f ine SQLITE_AUTH_
60f0: 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20 USER
6100: 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 (SQLITE_AUTH
6110: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
6120: 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 e SQLITE_OK_LOAD
6130: 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20 _PERMANENTLY
6140: 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 (SQLITE_OK | (1
6150: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 <<8))../*.** CAP
6160: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 I3REF: Flags For
6170: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 File Open Opera
6180: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tions.**.** Thes
6190: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 e bit values are
61a0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
61b0: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 e in the.** 3rd
61c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
61d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
61e0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 2()] interface a
61f0: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 nd.** in the 4th
6200: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
6210: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
6220: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f Open] method..*/
6230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6240: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 OPEN_READONLY
6250: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
6260: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
6270: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
6280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6290: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 OPEN_READWRITE
62a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
62b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
62c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
62d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
62e0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 OPEN_CREATE
62f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
6300: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
6310: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
6320: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6330: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
6340: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 SE 0x00000008
6350: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6370: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 OPEN_EXCLUSIVE
6380: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
6390: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
63a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
63b0: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 OPEN_AUTOPROXY
63c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0x00000020
63d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
63e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
63f0: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 OPEN_URI
6400: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0x00000040
6410: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
6420: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
6430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6440: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 OPEN_MEMORY
6450: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0x00000080
6460: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
6470: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
6480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6490: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 OPEN_MAIN_DB
64a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0x00000100
64b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
64c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
64d0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 OPEN_TEMP_DB
64e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0x00000200
64f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6510: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 OPEN_TRANSIENT_D
6520: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 B 0x00000400
6530: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6550: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
6560: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 L 0x00000800
6570: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6590: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
65a0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 L 0x00001000
65b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
65c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
65d0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 OPEN_SUBJOURNAL
65e0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0x00002000
65f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6600: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6610: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
6620: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 NAL 0x00004000
6630: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6650: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 OPEN_NOMUTEX
6660: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 0x00008000
6670: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
6680: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
6690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
66a0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 OPEN_FULLMUTEX
66b0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 0x00010000
66c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
66d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
66e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
66f0: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
6700: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 0x00020000
6710: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
6720: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
6730: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6740: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
6750: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 E 0x00040000
6760: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
6770: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
6780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6790: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 OPEN_WAL
67a0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 0x00080000
67b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
67c0: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 ../* Reserved:
67d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
67e0: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 0x00F0000
67f0: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 0 */../*.** CAPI
6800: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 3REF: Device Cha
6810: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a racteristics.**.
6820: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 ** The xDeviceCh
6830: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 aracteristics me
6840: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c thod of the [sql
6850: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
6860: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 .** object retur
6870: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 ns an integer wh
6880: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 ich is a vector
6890: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 of these.** bit
68a0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e values expressin
68b0: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 g I/O characteri
68c0: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 stics of the mas
68d0: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 s storage.** dev
68e0: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 ice that holds t
68f0: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 he file that the
6900: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
6910: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 hods].** refers
6920: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 to..**.** The SQ
6930: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6940: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 C property means
6950: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 that all writes
6960: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 of.** any size
6970: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
6980: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6990: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a OMICnnn values.*
69a0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 * mean that writ
69b0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 es of blocks tha
69c0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 t are nnn bytes
69d0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 in size and.** a
69e0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e re aligned to an
69f0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 address which i
6a00: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c s an integer mul
6a10: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 tiple of.** nnn
6a20: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
6a30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
6a40: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 FE_APPEND value
6a50: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 means.** that wh
6a60: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e en data is appen
6a70: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 ded to a file, t
6a80: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e he data is appen
6a90: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 ded.** first the
6aa0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 n the size of th
6ab0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 e file is extend
6ac0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 ed, never the ot
6ad0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e her.** way aroun
6ae0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 d. The SQLITE_I
6af0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
6b00: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
6b10: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 hat.** informati
6b20: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f on is written to
6b30: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d disk in the sam
6b40: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 e order as calls
6b50: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e .** to xWrite().
6b60: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
6b70: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 AP_POWERSAFE_OVE
6b80: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 RWRITE property
6b90: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 means that.** af
6ba0: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f ter reboot follo
6bb0: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 wing a crash or
6bc0: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 power loss, the
6bd0: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a only bytes in a.
6be0: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 ** file that wer
6bf0: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 e written at the
6c00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 application lev
6c10: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 el might have ch
6c20: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 anged.** and tha
6c30: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 t adjacent bytes
6c40: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 , even bytes wit
6c50: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 hin the same sec
6c60: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 tor are.** guara
6c70: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 nteed to be unch
6c80: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 anged. The SQLI
6c90: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 TE_IOCAP_UNDELET
6ca0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a ABLE_WHEN_OPEN.*
6cb0: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 * flag indicates
6cc0: 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e that a file can
6cd0: 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 not be deleted w
6ce0: 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a hen open. The.*
6cf0: 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 * SQLITE_IOCAP_I
6d00: 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e MMUTABLE flag in
6d10: 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 dicates that the
6d20: 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 file is on.** r
6d30: 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 ead-only media a
6d40: 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 nd cannot be cha
6d50: 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f nged even by pro
6d60: 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 cesses with.** e
6d70: 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 levated privileg
6d80: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 es..**.** The SQ
6d90: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 LITE_IOCAP_BATCH
6da0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
6db0: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
6dc0: 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 66 69 underlying.** fi
6dd0: 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74 lesystem support
6de0: 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70 6c 65 s doing multiple
6df0: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e write operation
6e00: 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77 68 65 s atomically whe
6e10: 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69 74 65 n those.** write
6e20: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 operations are
6e30: 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b 53 51 bracketed by [SQ
6e40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e LITE_FCNTL_BEGIN
6e50: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 61 _ATOMIC_WRITE] a
6e60: 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 nd.** [SQLITE_FC
6e70: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 NTL_COMMIT_ATOMI
6e80: 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23 64 65 C_WRITE]..*/.#de
6e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6ea0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 P_ATOMIC
6eb0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6ec0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 001.#define SQLI
6ed0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 TE_IOCAP_ATOMIC5
6ee0: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 12
6ef0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 0x00000002.#defi
6f00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6f10: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 ATOMIC1K
6f20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
6f30: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
6f40: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 _IOCAP_ATOMIC2K
6f50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
6f60: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 00000008.#define
6f70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6f80: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 OMIC4K
6f90: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 0x00000010.
6fa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6fb0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 OCAP_ATOMIC8K
6fc0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
6fd0: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 000020.#define S
6fe0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
6ff0: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 IC16K
7000: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 0x00000040.#d
7010: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
7020: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 AP_ATOMIC32K
7030: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
7040: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0080.#define SQL
7050: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
7060: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 64K
7070: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 0x00000100.#def
7080: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
7090: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 _SAFE_APPEND
70a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 0x000002
70b0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
70c0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
70d0: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 AL 0
70e0: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e x00000400.#defin
70f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 e SQLITE_IOCAP_U
7100: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f NDELETABLE_WHEN_
7110: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 OPEN 0x00000800
7120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7130: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f IOCAP_POWERSAFE_
7140: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 OVERWRITE 0x0
7150: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 0001000.#define
7160: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d SQLITE_IOCAP_IMM
7170: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 UTABLE
7180: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 0x00002000.#
7190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
71a0: 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 CAP_BATCH_ATOMIC
71b0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
71c0: 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 04000../*.** CAP
71d0: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b I3REF: File Lock
71e0: 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a ing Levels.**.**
71f0: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 SQLite uses one
7200: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 of these intege
7210: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 r values as the
7220: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 second.** argume
7230: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d nt to calls it m
7240: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 akes to the xLoc
7250: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 k() and xUnlock(
7260: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 ) methods.** of
7270: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d an [sqlite3_io_m
7280: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a ethods] object..
7290: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
72a0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 E_LOCK_NONE
72b0: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 0.#define S
72c0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
72d0: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 D 1.#defi
72e0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 ne SQLITE_LOCK_R
72f0: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 ESERVED 2.#
7300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
7310: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 CK_PENDING
7320: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 3.#define SQLIT
7330: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 E_LOCK_EXCLUSIVE
7340: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 4../*.** CA
7350: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e PI3REF: Synchron
7360: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 ization Type Fla
7370: 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 gs.**.** When SQ
7380: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 Lite invokes the
7390: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 xSync() method
73a0: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 of an.** [sqlite
73b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
73c0: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 ject it uses a c
73d0: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a ombination of.**
73e0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 these integer v
73f0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 alues as the sec
7400: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a ond argument..**
7410: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c .** When the SQL
7420: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c ITE_SYNC_DATAONL
7430: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 Y flag is used,
7440: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 it means that th
7450: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 e.** sync operat
7460: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 ion only needs t
7470: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 o flush data to
7480: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 mass storage. I
7490: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 node.** informat
74a0: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 ion need not be
74b0: 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 flushed. If the
74c0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 lower four bits
74d0: 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 of the flag.** e
74e0: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 qual SQLITE_SYNC
74f0: 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 _NORMAL, that me
7500: 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 ans to use norma
7510: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 l fsync() semant
7520: 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c ics..** If the l
7530: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 ower four bits e
7540: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 qual SQLITE_SYNC
7550: 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e _FULL, that mean
7560: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 s.** to use Mac
7570: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 OS X style fulls
7580: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 ync instead of f
7590: 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f sync()..**.** Do
75a0: 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 not confuse the
75b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 SQLITE_SYNC_NOR
75c0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 MAL and SQLITE_S
75d0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a YNC_FULL flags.*
75e0: 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 * with the [PRAG
75f0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d MA synchronous]=
7600: 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 NORMAL and [PRAG
7610: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d MA synchronous]=
7620: 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 FULL.** settings
7630: 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e . The [synchron
7640: 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 ous pragma] dete
7650: 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c rmines when call
7660: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e s to the.** xSyn
7670: 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 c VFS method occ
7680: 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 ur and applies u
7690: 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 niformly across
76a0: 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a all platforms..*
76b0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e * The SQLITE_SYN
76c0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c C_NORMAL and SQL
76d0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c ITE_SYNC_FULL fl
76e0: 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f ags determine ho
76f0: 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f w.** energetic o
7700: 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f r rigorous or fo
7710: 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 rceful the sync
7720: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 operations are a
7730: 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 nd.** only make
7740: 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 a difference on
7750: 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 Mac OSX for the
7760: 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 default SQLite c
7770: 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 ode..** (Third-p
7780: 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 arty VFS impleme
7790: 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 ntations might a
77a0: 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 lso make the dis
77b0: 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 tinction.** betw
77c0: 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f een SQLITE_SYNC_
77d0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 NORMAL and SQLIT
77e0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 E_SYNC_FULL, but
77f0: 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 among the.** op
7800: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 erating systems
7810: 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 natively support
7820: 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e ed by SQLite, on
7830: 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 ly Mac OSX.** ca
7840: 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 res about the di
7850: 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 fference.).*/.#d
7860: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e efine SQLITE_SYN
7870: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 C_NORMAL
7880: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 0x00002.#define
7890: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
78a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
78b0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
78c0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 _SYNC_DATAONLY
78d0: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 0x00010../*.
78e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
78f0: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 Interface Open F
7900: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a ile Handle.**.**
7910: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c An [sqlite3_fil
7920: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 e] object repres
7930: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c ents an open fil
7940: 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 e in the .** [sq
7950: 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 lite3_vfs | OS i
7960: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e nterface layer].
7970: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 Individual OS
7980: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 interface.** imp
7990: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c lementations wil
79a0: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 l.** want to sub
79b0: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 class this objec
79c0: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 t by appending a
79d0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
79e0: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 .** for their ow
79f0: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 n use. The pMet
7a00: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 hods entry is a
7a10: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
7a20: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
7a30: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 hods] object tha
7a40: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 t defines method
7a50: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 s for performing
7a60: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f .** I/O operatio
7a70: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 ns on the open f
7a80: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ile..*/.typedef
7a90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 struct sqlite3_f
7aa0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 ile sqlite3_file
7ab0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
7ac0: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 _file {. const
7ad0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
7ae0: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 o_methods *pMeth
7af0: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 ods; /* Methods
7b00: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c for an open fil
7b10: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e */.};../*.** C
7b20: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 API3REF: OS Inte
7b30: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 rface File Virtu
7b40: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 al Methods Objec
7b50: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 t.**.** Every fi
7b60: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 le opened by the
7b70: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f [sqlite3_vfs.xO
7b80: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 pen] method popu
7b90: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c lates an.** [sql
7ba0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
7bb0: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d t (or, more comm
7bc0: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 only, a subclass
7bd0: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
7be0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
7bf0: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 ) with a pointer
7c00: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
7c10: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a of this object..
7c20: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 ** This object d
7c30: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f efines the metho
7c40: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f ds used to perfo
7c50: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 rm various opera
7c60: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 tions.** against
7c70: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 the open file r
7c80: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 epresented by th
7c90: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d e [sqlite3_file]
7ca0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 object..**.** I
7cb0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 f the [sqlite3_v
7cc0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 fs.xOpen] method
7cd0: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 sets the sqlite
7ce0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 3_file.pMethods
7cf0: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 element .** to a
7d00: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 non-NULL pointe
7d10: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 r, then the sqli
7d20: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 te3_io_methods.x
7d30: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 Close method.**
7d40: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 may be invoked e
7d50: 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 ven if the [sqli
7d60: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 te3_vfs.xOpen] r
7d70: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 eported that it
7d80: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 failed. The.**
7d90: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 only way to prev
7da0: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 ent a call to xC
7db0: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 lose following a
7dc0: 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 failed [sqlite3
7dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 _vfs.xOpen].** i
7de0: 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 s for the [sqlit
7df0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f e3_vfs.xOpen] to
7e00: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 set the sqlite3
7e10: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 _file.pMethods e
7e20: 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c lement.** to NUL
7e30: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 L..**.** The fla
7e40: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
7e50: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 Sync may be one
7e60: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f of [SQLITE_SYNC_
7e70: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 NORMAL] or.** [S
7e80: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d QLITE_SYNC_FULL]
7e90: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f . The first cho
7ea0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 ice is the norma
7eb0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 l fsync()..** Th
7ec0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 e second choice
7ed0: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 is a Mac OS X st
7ee0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 yle fullsync. T
7ef0: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f he [SQLITE_SYNC_
7f00: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 DATAONLY].** fla
7f10: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e g may be ORed in
7f20: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
7f30: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 t only the data
7f40: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 of the file.** a
7f50: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 nd not its inode
7f60: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e needs to be syn
7f70: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ced..**.** The i
7f80: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f nteger values to
7f90: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e xLock() and xUn
7fa0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f lock() are one o
7fb0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 f.** <ul>.** <li
7fc0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e > [SQLITE_LOCK_N
7fd0: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ONE],.** <li> [S
7fe0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
7ff0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
8000: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
8010: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
8020: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 ITE_LOCK_PENDING
8030: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ], or.** <li> [S
8040: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
8050: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a SIVE]..** </ul>.
8060: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 ** xLock() incre
8070: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 ases the lock. x
8080: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 Unlock() decreas
8090: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 es the lock..**
80a0: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 The xCheckReserv
80b0: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 edLock() method
80c0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 checks whether a
80d0: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ny database conn
80e0: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 ection,.** eithe
80f0: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 r in this proces
8100: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 s or in some oth
8110: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 er process, is h
8120: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 olding a RESERVE
8130: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f D,.** PENDING, o
8140: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b r EXCLUSIVE lock
8150: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 on the file. I
8160: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a t returns true.*
8170: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b * if such a lock
8180: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 exists and fals
8190: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a e otherwise..**.
81a0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 ** The xFileCont
81b0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 rol() method is
81c0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 a generic interf
81d0: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 ace that allows
81e0: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d custom.** VFS im
81f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f plementations to
8200: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f directly contro
8210: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 l an open file u
8220: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
8230: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
8240: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 l()] interface.
8250: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 The second "op"
8260: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a argument is an.
8270: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 ** integer opcod
8280: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 e. The third ar
8290: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 gument is a gene
82a0: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 ric pointer inte
82b0: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 nded to.** point
82c0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 to a structure
82d0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e that may contain
82e0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 arguments or sp
82f0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a ace in which to.
8300: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 ** write return
8310: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 values. Potenti
8320: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c al uses for xFil
8330: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 eControl() might
8340: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 be.** functions
8350: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b to enable block
8360: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 ing locks with t
8370: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e imeouts, to chan
8380: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e ge the.** lockin
8390: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 g strategy (for
83a0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 example to use d
83b0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 ot-file locks),
83c0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 to inquire.** ab
83d0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f out the status o
83e0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 f a lock, or to
83f0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b break stale lock
8400: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a s. The SQLite.*
8410: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 * core reserves
8420: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 all opcodes less
8430: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 than 100 for it
8440: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 s own use..** A
8450: 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 [file control op
8460: 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 codes | list of
8470: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 opcodes] less th
8480: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 an 100 is availa
8490: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 ble..** Applicat
84a0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 ions that define
84b0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 a custom xFileC
84c0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 ontrol method sh
84d0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 ould use opcodes
84e0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e .** greater than
84f0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 100 to avoid co
8500: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d nflicts. VFS im
8510: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 plementations sh
8520: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b ould.** return [
8530: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d SQLITE_NOTFOUND]
8540: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f for file contro
8550: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 l opcodes that t
8560: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 hey do not.** re
8570: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 cognize..**.** T
8580: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 he xSectorSize()
8590: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
85a0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 the sector size
85b0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 of the.** device
85c0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 that underlies
85d0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 the file. The s
85e0: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 ector size is th
85f0: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 e.** minimum wri
8600: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 te that can be p
8610: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 erformed without
8620: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f disturbing.** o
8630: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 ther bytes in th
8640: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 e file. The xDe
8650: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
8660: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 ics().** method
8670: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 returns a bit ve
8680: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 ctor describing
8690: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 behaviors of the
86a0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 .** underlying d
86b0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c evice:.**.** <ul
86c0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
86d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a E_IOCAP_ATOMIC].
86e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
86f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d IOCAP_ATOMIC512]
8700: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8710: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d _IOCAP_ATOMIC1K]
8720: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8730: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d _IOCAP_ATOMIC2K]
8740: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8750: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d _IOCAP_ATOMIC4K]
8760: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8770: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d _IOCAP_ATOMIC8K]
8780: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8790: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b _IOCAP_ATOMIC16K
87a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
87b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 E_IOCAP_ATOMIC32
87c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
87d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 TE_IOCAP_ATOMIC6
87e0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 4K].** <li> [SQL
87f0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
8800: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b PPEND].** <li> [
8810: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 SQLITE_IOCAP_SEQ
8820: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e UENTIAL].** <li>
8830: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 [SQLITE_IOCAP_U
8840: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f NDELETABLE_WHEN_
8850: 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 OPEN].** <li> [S
8860: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 QLITE_IOCAP_POWE
8870: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d RSAFE_OVERWRITE]
8880: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8890: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 _IOCAP_IMMUTABLE
88a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
88b0: 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 E_IOCAP_BATCH_AT
88c0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a OMIC].** </ul>.*
88d0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f *.** The SQLITE_
88e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f IOCAP_ATOMIC pro
88f0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
8900: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a all writes of.*
8910: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 * any size are a
8920: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
8930: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e TE_IOCAP_ATOMICn
8940: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 nn values.** mea
8950: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 n that writes of
8960: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 blocks that are
8970: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 nnn bytes in si
8980: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c ze and.** are al
8990: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 igned to an addr
89a0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 ess which is an
89b0: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 integer multiple
89c0: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 of.** nnn are a
89d0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
89e0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
89f0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 PEND value means
8a00: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 .** that when da
8a10: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 ta is appended t
8a20: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 o a file, the da
8a30: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a ta is appended.*
8a40: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 * first then the
8a50: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c size of the fil
8a60: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e e is extended, n
8a70: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a ever the other.*
8a80: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 * way around. T
8a90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
8aa0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 SEQUENTIAL prope
8ab0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a rty means that.*
8ac0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
8ad0: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b written to disk
8ae0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 in the same ord
8af0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 er as calls.** t
8b00: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a o xWrite()..**.*
8b10: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 * If xRead() ret
8b20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 urns SQLITE_IOER
8b30: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 R_SHORT_READ it
8b40: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a must also fill.*
8b50: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 * in the unread
8b60: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 portions of the
8b70: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f buffer with zero
8b80: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a s. A VFS that.*
8b90: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d * fails to zero-
8ba0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 fill short reads
8bb0: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 might seem to w
8bc0: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a ork. However,.*
8bd0: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 * failure to zer
8be0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 o-fill short rea
8bf0: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c ds will eventual
8c00: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 ly lead to.** da
8c10: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f tabase corruptio
8c20: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 n..*/.typedef st
8c30: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
8c40: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f methods sqlite3_
8c50: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 io_methods;.stru
8c60: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
8c70: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 thods {. int iV
8c80: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a ersion;. int (*
8c90: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f xClose)(sqlite3_
8ca0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
8cb0: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 xRead)(sqlite3_f
8cc0: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 ile*, void*, int
8cd0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 iAmt, sqlite3_i
8ce0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 nt64 iOfst);. i
8cf0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c nt (*xWrite)(sql
8d00: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 ite3_file*, cons
8d10: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d t void*, int iAm
8d20: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 t, sqlite3_int64
8d30: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 iOfst);. int (
8d40: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 *xTruncate)(sqli
8d50: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
8d60: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a e3_int64 size);.
8d70: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 int (*xSync)(s
8d80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
8d90: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 t flags);. int
8da0: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c (*xFileSize)(sql
8db0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 ite3_file*, sqli
8dc0: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 te3_int64 *pSize
8dd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b );. int (*xLock
8de0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
8df0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 int);. int (*x
8e00: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f Unlock)(sqlite3_
8e10: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 file*, int);. i
8e20: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 nt (*xCheckReser
8e30: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 vedLock)(sqlite3
8e40: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 _file*, int *pRe
8e50: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sOut);. int (*x
8e60: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c FileControl)(sql
8e70: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
8e80: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b op, void *pArg);
8e90: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 . int (*xSector
8ea0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 Size)(sqlite3_fi
8eb0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 le*);. int (*xD
8ec0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 eviceCharacteris
8ed0: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 tics)(sqlite3_fi
8ee0: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f le*);. /* Metho
8ef0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c ds above are val
8f00: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 id for version 1
8f10: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d */. int (*xShm
8f20: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c Map)(sqlite3_fil
8f30: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 e*, int iPg, int
8f40: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 pgsz, int, void
8f50: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 volatile**);.
8f60: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 int (*xShmLock)(
8f70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
8f80: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e nt offset, int n
8f90: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 , int flags);.
8fa0: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 void (*xShmBarri
8fb0: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 er)(sqlite3_file
8fc0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d *);. int (*xShm
8fd0: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 Unmap)(sqlite3_f
8fe0: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 ile*, int delete
8ff0: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 Flag);. /* Meth
9000: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 ods above are va
9010: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 lid for version
9020: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 2 */. int (*xFe
9030: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c tch)(sqlite3_fil
9040: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
9050: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 4 iOfst, int iAm
9060: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 t, void **pp);.
9070: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 int (*xUnfetch)
9080: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
9090: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f sqlite3_int64 iO
90a0: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 fst, void *p);.
90b0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 /* Methods abov
90c0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 e are valid for
90d0: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f version 3 */. /
90e0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 * Additional met
90f0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 hods may be adde
9100: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
9110: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a ases */.};../*.*
9120: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e * CAPI3REF: Stan
9130: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f dard File Contro
9140: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 l Opcodes.** KEY
9150: 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e WORDS: {file con
9160: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 trol opcodes} {f
9170: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f ile control opco
9180: 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 de}.**.** These
9190: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
91a0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f s are opcodes fo
91b0: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 r the xFileContr
91c0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 ol method.** of
91d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
91e0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
91f0: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c and for the [sql
9200: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
9210: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 l()].** interfac
9220: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a e..**.** <ul>.**
9230: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
9240: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a NTL_LOCKSTATE]].
9250: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
9260: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 CNTL_LOCKSTATE]
9270: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 opcode is used f
9280: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 or debugging. T
9290: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 his.** opcode ca
92a0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f uses the xFileCo
92b0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 ntrol method to
92c0: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e write the curren
92d0: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 t state of.** th
92e0: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b e lock (one of [
92f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
9300: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ], [SQLITE_LOCK_
9310: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c SHARED],.** [SQL
9320: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
9330: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b D], [SQLITE_LOCK
9340: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 _PENDING], or [S
9350: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
9360: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 SIVE]).** into a
9370: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 n integer that t
9380: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 he pArg argument
9390: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 points to. This
93a0: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 capability.** i
93b0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 s used during te
93c0: 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c sting and is onl
93d0: 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e y available when
93e0: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 the SQLITE_TEST
93f0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 .** compile-time
9400: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e option is used.
9410: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
9420: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 ITE_FCNTL_SIZE_H
9430: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 INT]].** The [SQ
9440: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f LITE_FCNTL_SIZE_
9450: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 HINT] opcode is
9460: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 used by SQLite t
9470: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a o give the VFS.*
9480: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f * layer a hint o
9490: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 f how large the
94a0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 database file wi
94b0: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 ll grow to be du
94c0: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 ring the.** curr
94d0: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e ent transaction.
94e0: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e This hint is n
94f0: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f ot guaranteed to
9500: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 be accurate but
9510: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 it.** is often
9520: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 close. The unde
9530: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 rlying VFS might
9540: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c choose to preal
9550: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a locate database.
9560: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 ** file space ba
9570: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 sed on this hint
9580: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c in order to hel
9590: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 p writes to the
95a0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 database.** file
95b0: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a run faster..**.
95c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
95d0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 FCNTL_CHUNK_SIZE
95e0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
95f0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 E_FCNTL_CHUNK_SI
9600: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 ZE] opcode is us
9610: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 ed to request th
9620: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 at the VFS.** ex
9630: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 tends and trunca
9640: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 tes the database
9650: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 file in chunks
9660: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 of a size specif
9670: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 ied.** by the us
9680: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 er. The fourth a
9690: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
96a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
96b0: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 ()] should .** p
96c0: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 oint to an integ
96d0: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f er (type int) co
96e0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 ntaining the new
96f0: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 chunk-size to u
9700: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f se.** for the no
9710: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 minated database
9720: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 . Allocating dat
9730: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 abase file space
9740: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 in large.** chu
9750: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 nks (say 1MB at
9760: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 a time), may red
9770: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 uce file-system
9780: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e fragmentation an
9790: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 d.** improve per
97a0: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 formance on some
97b0: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 systems..**.**
97c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
97d0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d TL_FILE_POINTER]
97e0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
97f0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e _FCNTL_FILE_POIN
9800: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 TER] opcode is u
9810: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 sed to obtain a
9820: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 pointer.** to th
9830: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d e [sqlite3_file]
9840: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 object associat
9850: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 ed with a partic
9860: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a ular database.**
9870: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 connection. Se
9880: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 e also [SQLITE_F
9890: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 CNTL_JOURNAL_POI
98a0: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 NTER]..**.** <li
98b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
98c0: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d JOURNAL_POINTER]
98d0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
98e0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 _FCNTL_JOURNAL_P
98f0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 OINTER] opcode i
9900: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e s used to obtain
9910: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
9920: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
9930: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 le] object assoc
9940: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a iated with the j
9950: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74 ournal file (eit
9960: 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c her.** the [roll
9970: 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 back journal] or
9980: 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61 the [write-ahea
9990: 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61 d log]) for a pa
99a0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 rticular databas
99b0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e e.** connection.
99c0: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 See also [SQLI
99d0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f TE_FCNTL_FILE_PO
99e0: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c INTER]..**.** <l
99f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
9a00: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a _SYNC_OMITTED]].
9a10: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 ** No longer in
9a20: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b use..**.** <li>[
9a30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 [SQLITE_FCNTL_SY
9a40: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c NC]].** The [SQL
9a50: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 ITE_FCNTL_SYNC]
9a60: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 opcode is genera
9a70: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 ted internally b
9a80: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 y SQLite and.**
9a90: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 sent to the VFS
9aa0: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f immediately befo
9ab0: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 re the xSync met
9ac0: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f hod is invoked o
9ad0: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 n a.** database
9ae0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e file descriptor.
9af0: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e Or, if the xSyn
9b00: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 c method is not
9b10: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 invoked .** beca
9b20: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 use the user has
9b30: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 configured SQLi
9b40: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 te with .** [PRA
9b50: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 GMA synchronous
9b60: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f | PRAGMA synchro
9b70: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 nous=OFF] it is
9b80: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 invoked in place
9b90: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e .** of the xSyn
9ba0: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 c method. In mos
9bb0: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 t cases, the poi
9bc0: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 nter argument pa
9bd0: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 ssed with.** thi
9be0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 s file-control i
9bf0: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c s NULL. However,
9c00: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 if the database
9c10: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 file is being s
9c20: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 ynced.** as part
9c30: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 of a multi-data
9c40: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 base commit, the
9c50: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 argument points
9c60: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e to a nul-termin
9c70: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 ated.** string c
9c80: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 ontaining the tr
9c90: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 ansactions maste
9ca0: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e r-journal file n
9cb0: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 ame. VFSes that
9cc0: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 .** do not need
9cd0: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 this signal shou
9ce0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f ld silently igno
9cf0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 re this opcode.
9d00: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a Applications .**
9d10: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c should not call
9d20: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
9d30: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 ontrol()] with t
9d40: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f his opcode as do
9d50: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 ing so may .** d
9d60: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 isrupt the opera
9d70: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 tion of the spec
9d80: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 ialized VFSes th
9d90: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 at do require it
9da0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b . .**.** <li>[[
9db0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d SQLITE_FCNTL_COM
9dc0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a MIT_PHASETWO]].*
9dd0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
9de0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 NTL_COMMIT_PHASE
9df0: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 TWO] opcode is g
9e00: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 enerated interna
9e10: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a lly by SQLite.**
9e20: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 and sent to the
9e30: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 VFS after a tra
9e40: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 nsaction has bee
9e50: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 n committed imme
9e60: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 diately.** but b
9e70: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 efore the databa
9e80: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 se is unlocked.
9e90: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f VFSes that do no
9ea0: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e t need this sign
9eb0: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c al.** should sil
9ec0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 ently ignore thi
9ed0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 s opcode. Applic
9ee0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f ations should no
9ef0: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 t call.** [sqlit
9f00: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
9f10: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 )] with this opc
9f20: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 ode as doing so
9f30: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 may disrupt the
9f40: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 .** operation of
9f50: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 the specialized
9f60: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 VFSes that do r
9f70: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a equire it. .**.
9f80: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
9f90: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 FCNTL_WIN32_AV_R
9fa0: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b ETRY]].** ^The [
9fb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
9fc0: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 32_AV_RETRY] opc
9fd0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 ode is used to c
9fe0: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 onfigure automat
9ff0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e ic.** retry coun
a000: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 ts and intervals
a010: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 for certain dis
a020: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 k I/O operations
a030: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 for the.** wind
a040: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 ows [VFS] in ord
a050: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f er to provide ro
a060: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 bustness in the
a070: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 presence of.** a
a080: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 nti-virus progra
a090: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c ms. By default,
a0a0: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 the windows VFS
a0b0: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 will retry file
a0c0: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 read,.** file w
a0d0: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 rite, and file d
a0e0: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 elete operations
a0f0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c up to 10 times,
a100: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a with a delay.**
a110: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f of 25 milliseco
a120: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 nds before the f
a130: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 irst retry and w
a140: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e ith the delay in
a150: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 creasing.** by a
a160: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 n additional 25
a170: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 milliseconds wit
a180: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e h each subsequen
a190: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a t retry. This.*
a1a0: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 * opcode allows
a1b0: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 these two values
a1c0: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 (10 retries and
a1d0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 25 milliseconds
a1e0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f of delay).** to
a1f0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 be adjusted. T
a200: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 he values are ch
a210: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 anged for all da
a220: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
a230: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 ns.** within the
a240: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 same process.
a250: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 The argument is
a260: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
a270: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 array of two.**
a280: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 integers where t
a290: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 he first integer
a2a0: 20 69 73 20 74 68 65 20 6e 65 77 20 72 65 74 72 is the new retr
a2b0: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 y count and the
a2c0: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 second.** intege
a2d0: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 r is the delay.
a2e0: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 If either integ
a2f0: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 er is negative,
a300: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 then the setting
a310: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 .** is not chang
a320: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 ed but instead t
a330: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f he prior value o
a340: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 f that setting i
a350: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 s written.** int
a360: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 o the array entr
a370: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 y, allowing the
a380: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 current retry se
a390: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 ttings to be.**
a3a0: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 interrogated. T
a3b0: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d he zDbName param
a3c0: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e eter is ignored.
a3d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
a3e0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 ITE_FCNTL_PERSIS
a3f0: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 T_WAL]].** ^The
a400: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 [SQLITE_FCNTL_PE
a410: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 RSIST_WAL] opcod
a420: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 e is used to set
a430: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a or query the.**
a440: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c persistent [WAL
a450: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c | Write Ahead L
a460: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 og] setting. By
a470: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 default, the au
a480: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 xiliary.** write
a490: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 ahead log and s
a4a0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c hared memory fil
a4b0: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e es used for tran
a4c0: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a saction control.
a4d0: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 ** are automatic
a4e0: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 ally deleted whe
a4f0: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e n the latest con
a500: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 nection to the d
a510: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 atabase.** close
a520: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 s. Setting pers
a530: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 istent WAL mode
a540: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c causes those fil
a550: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 es to persist af
a560: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 ter.** close. P
a570: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 ersisting the fi
a580: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 les is useful wh
a590: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 en other process
a5a0: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a es that do not.*
a5b0: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 * have write per
a5c0: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 mission on the d
a5d0: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e irectory contain
a5e0: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 ing the database
a5f0: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f file want.** to
a600: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 read the databa
a610: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 se file, as the
a620: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d WAL and shared m
a630: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 emory files must
a640: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 exist.** in ord
a650: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 er for the datab
a660: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 ase to be readab
a670: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 le. The fourth
a680: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
a690: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
a6a0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 ntrol()] for thi
a6b0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 s opcode should
a6c0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 be a pointer to
a6d0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 an integer..** T
a6e0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 hat integer is 0
a6f0: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 to disable pers
a700: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 istent WAL mode
a710: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 or 1 to enable p
a720: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c ersistent.** WAL
a730: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 mode. If the i
a740: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 nteger is -1, th
a750: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 en it is overwri
a760: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 tten with the cu
a770: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 rrent.** WAL per
a780: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 sistence setting
a790: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
a7a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 LITE_FCNTL_POWER
a7b0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d SAFE_OVERWRITE]]
a7c0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
a7d0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 _FCNTL_POWERSAFE
a7e0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f _OVERWRITE] opco
a7f0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 de is used to se
a800: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a t or query the.*
a810: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f * persistent "po
a820: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 wersafe-overwrit
a830: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 e" or "PSOW" set
a840: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 ting. The PSOW
a850: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 setting.** deter
a860: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 mines the [SQLIT
a870: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 E_IOCAP_POWERSAF
a880: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 E_OVERWRITE] bit
a890: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 of the.** xDevi
a8a0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 ceCharacteristic
a8b0: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 s methods. The f
a8c0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
a8d0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 to.** [sqlite3_f
a8e0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 ile_control()] f
a8f0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 or this opcode s
a900: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 hould be a point
a910: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 er to an integer
a920: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 ..** That intege
a930: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c r is 0 to disabl
a940: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f e zero-damage mo
a950: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c de or 1 to enabl
a960: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a e zero-damage.**
a970: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 mode. If the i
a980: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 nteger is -1, th
a990: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 en it is overwri
a9a0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 tten with the cu
a9b0: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 rrent.** zero-da
a9c0: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e mage mode settin
a9d0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 g..**.** <li>[[S
a9e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 QLITE_FCNTL_OVER
a9f0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 WRITE]].** ^The
aa00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 [SQLITE_FCNTL_OV
aa10: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 ERWRITE] opcode
aa20: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 is invoked by SQ
aa30: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 Lite after openi
aa40: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 ng.** a write tr
aa50: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 ansaction to ind
aa60: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 icate that, unle
aa70: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 ss it is rolled
aa80: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a back for some.**
aa90: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 reason, the ent
aaa0: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c ire database fil
aab0: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 e will be overwr
aac0: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 itten by the cur
aad0: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 rent .** transac
aae0: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 tion. This is us
aaf0: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 ed by VACUUM ope
ab00: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c rations..**.** <
ab10: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
ab20: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e L_VFSNAME]].** ^
ab30: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
ab40: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 L_VFSNAME] opcod
ab50: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
ab60: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 obtain the name
ab70: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 s of.** all [VFS
ab80: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 es] in the VFS s
ab90: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 tack. The names
aba0: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 are of all VFS
abb0: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a shims and the.**
abc0: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 final bottom-le
abd0: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 vel VFS are writ
abe0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 ten into memory
abf0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a obtained from .*
ac00: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f * [sqlite3_mallo
ac10: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 c()] and the res
ac20: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e ult is stored in
ac30: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 the char* varia
ac40: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 ble.** that the
ac50: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
ac60: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c of [sqlite3_fil
ac70: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 e_control()] poi
ac80: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 nts to..** The c
ac90: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 aller is respons
aca0: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 ible for freeing
acb0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e the memory when
acc0: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a done. As with.
acd0: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 ** all file-cont
ace0: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 rol actions, the
acf0: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 re is no guarant
ad00: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c ee that this wil
ad10: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f l actually.** do
ad20: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c anything. Call
ad30: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 ers should initi
ad40: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 alize the char*
ad50: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 variable to a NU
ad60: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e LL.** pointer in
ad70: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d case this file-
ad80: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 control is not i
ad90: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 mplemented. Thi
ada0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a s file-control.*
adb0: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f * is intended fo
adc0: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 r diagnostic use
add0: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 only..**.** <li
ade0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
adf0: 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a VFS_POINTER]].**
ae00: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^The [SQLITE_FC
ae10: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d NTL_VFS_POINTER]
ae20: 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 opcode finds a
ae30: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 pointer to the t
ae40: 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 op-level.** [VFS
ae50: 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e es] currently in
ae60: 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 use. ^(The arg
ae70: 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 ument X in.** sq
ae80: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
ae90: 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e ol(db,SQLITE_FCN
aea0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 TL_VFS_POINTER,X
aeb0: 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 ) must be.** of
aec0: 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 type "[sqlite3_v
aed0: 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f fs] **". This o
aee0: 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 pcodes will set
aef0: 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 *X.** to a point
af00: 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 er to the top-le
af10: 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 vel VFS.)^.** ^W
af20: 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 hen there are mu
af30: 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 ltiple VFS shims
af40: 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 in the stack, t
af50: 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 his opcode finds
af60: 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f the.** upper-mo
af70: 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a st shim only..**
af80: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
af90: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a _FCNTL_PRAGMA]].
afa0: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b ** ^Whenever a [
afb0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e PRAGMA] statemen
afc0: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 t is parsed, an
afd0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
afe0: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 AGMA] .** file c
aff0: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 ontrol is sent t
b000: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 o the open [sqli
b010: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
b020: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a corresponding.*
b030: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 * to the databas
b040: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 e file to which
b050: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 the pragma state
b060: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 ment refers. ^Th
b070: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f e argument.** to
b080: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e the [SQLITE_FCN
b090: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 TL_PRAGMA] file
b0a0: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 control is an ar
b0b0: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 ray of.** pointe
b0c0: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 rs to strings (c
b0d0: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 har**) in which
b0e0: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 the second eleme
b0f0: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a nt of the array.
b100: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ** is the name o
b110: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 f the pragma and
b120: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 the third eleme
b130: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 nt is the argume
b140: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 nt to the.** pra
b150: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 gma or NULL if t
b160: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f he pragma has no
b170: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 argument. ^The
b180: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a handler for an.
b190: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c ** [SQLITE_FCNTL
b1a0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
b1b0: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e ntrol can option
b1c0: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 ally make the fi
b1d0: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f rst element.** o
b1e0: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 f the char** arg
b1f0: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 ument point to a
b200: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 string obtained
b210: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
b220: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 printf()].** or
b230: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 the equivalent a
b240: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 nd that string w
b250: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 ill become the r
b260: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 esult of the pra
b270: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 gma or.** the er
b280: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 ror message if t
b290: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e he pragma fails.
b2a0: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c ^If the.** [SQL
b2b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
b2c0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 ] file control r
b2d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e eturns [SQLITE_N
b2e0: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e OTFOUND], then n
b2f0: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d ormal .** [PRAGM
b300: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f A] processing co
b310: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 ntinues. ^If th
b320: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
b330: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 PRAGMA].** file
b340: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 control returns
b350: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 [SQLITE_OK], the
b360: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 n the parser ass
b370: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a umes that the.**
b380: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 VFS has handled
b390: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 the PRAGMA itse
b3a0: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 lf and the parse
b3b0: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f r generates a no
b3c0: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 -op.** prepared
b3d0: 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 statement if res
b3e0: 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 ult string is NU
b3f0: 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 LL, or that retu
b400: 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 rns a copy.** of
b410: 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 the result stri
b420: 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 ng if the string
b430: 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a is non-NULL..**
b440: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 ^If the [SQLITE
b450: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 _FCNTL_PRAGMA] f
b460: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 ile control retu
b470: 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c rns.** any resul
b480: 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 t code other tha
b490: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 n [SQLITE_OK] or
b4a0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e [SQLITE_NOTFOUN
b4b0: 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a D], that means.*
b4c0: 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 * that the VFS e
b4d0: 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 ncountered an er
b4e0: 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 ror while handli
b4f0: 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 ng the [PRAGMA]
b500: 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 and the.** compi
b510: 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 lation of the PR
b520: 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 AGMA fails with
b530: 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 an error. ^The
b540: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
b550: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f AGMA].** file co
b560: 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 ntrol occurs at
b570: 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 the beginning of
b580: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e pragma statemen
b590: 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 t analysis and s
b5a0: 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 o.** it is able
b5b0: 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c to override buil
b5c0: 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 t-in [PRAGMA] st
b5d0: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
b5e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
b5f0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d TL_BUSYHANDLER]]
b600: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
b610: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c _FCNTL_BUSYHANDL
b620: 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 ER].** file-cont
b630: 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b rol may be invok
b640: 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 ed by SQLite on
b650: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
b660: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 e handle.** shor
b670: 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 tly after it is
b680: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 opened in order
b690: 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 to provide a cus
b6a0: 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 tom VFS with acc
b6b0: 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f ess.** to the co
b6c0: 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 nnections busy-h
b6d0: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e andler callback.
b6e0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 The argument is
b6f0: 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a of type (void *
b700: 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 *).** - an array
b710: 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 of two (void *)
b720: 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 values. The fir
b730: 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 st (void *) actu
b740: 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 ally points.** t
b750: 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 o a function of
b760: 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f type (int (*)(vo
b770: 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 id *)). In order
b780: 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 to invoke the c
b790: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 onnections.** bu
b7a0: 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 sy-handler, this
b7b0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 function should
b7c0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
b7d0: 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 the second (voi
b7e0: 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 d *) in.** the a
b7f0: 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 rray as the only
b800: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 argument. If it
b810: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
b820: 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 o, then the oper
b830: 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 ation.** should
b840: 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 be retried. If i
b850: 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 t returns zero,
b860: 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 the custom VFS s
b870: 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 hould abandon th
b880: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 e.** current ope
b890: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c ration..**.** <l
b8a0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
b8b0: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a _TEMPFILENAME]].
b8c0: 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 ** ^Application
b8d0: 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b can invoke the [
b8e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d SQLITE_FCNTL_TEM
b8f0: 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d PFILENAME] file-
b900: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 control.** to ha
b910: 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 ve SQLite genera
b920: 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 te a.** temporar
b930: 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 y filename using
b940: 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 the same algori
b950: 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c thm that is foll
b960: 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 owed to generate
b970: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 .** temporary fi
b980: 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 lenames for TEMP
b990: 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 tables and othe
b9a0: 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e r internal uses.
b9b0: 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e The.** argumen
b9c0: 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 t should be a ch
b9d0: 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 ar** which will
b9e0: 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 be filled with t
b9f0: 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 he filename.** w
ba00: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f ritten into memo
ba10: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ry obtained from
ba20: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
ba30: 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 ()]. The caller
ba40: 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b should.** invok
ba50: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 e [sqlite3_free(
ba60: 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 )] on the result
ba70: 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f to avoid a memo
ba80: 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c ry leak..**.** <
ba90: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
baa0: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a L_MMAP_SIZE]].**
bab0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
bac0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 TL_MMAP_SIZE] fi
bad0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 le control is us
bae0: 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 ed to query or s
baf0: 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 et the.** maximu
bb00: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 m number of byte
bb10: 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 s that will be u
bb20: 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d sed for memory-m
bb30: 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 apped I/O..** Th
bb40: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 e argument is a
bb50: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c pointer to a val
bb60: 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 ue of type sqlit
bb70: 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a e3_int64 that.**
bb80: 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 is an advisory
bb90: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
bba0: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 f bytes in the f
bbb0: 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 ile to memory ma
bbc0: 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 p. The.** point
bbd0: 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 er is overwritte
bbe0: 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 n with the old v
bbf0: 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 alue. The limit
bc00: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 is not changed
bc10: 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 if.** the value
bc20: 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 originally point
bc30: 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 ed to is negativ
bc40: 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 e, and so the cu
bc50: 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 rrent limit .**
bc60: 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 can be queried b
bc70: 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 y passing in a p
bc80: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 ointer to a nega
bc90: 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 tive number. Th
bca0: 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 is.** file-contr
bcb0: 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 ol is used inter
bcc0: 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 nally to impleme
bcd0: 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f nt [PRAGMA mmap_
bce0: 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 size]..**.** <li
bcf0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
bd00: 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b TRACE]].** The [
bd10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 SQLITE_FCNTL_TRA
bd20: 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c CE] file control
bd30: 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f provides adviso
bd40: 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a ry information.*
bd50: 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f * to the VFS abo
bd60: 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68 ut what the high
bd70: 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 er layers of the
bd80: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 SQLite stack ar
bd90: 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 e doing..** This
bda0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 file control is
bdb0: 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 used by some VF
bdc0: 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69 S activity traci
bdd0: 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 ng [shims]..** T
bde0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 he argument is a
bdf0: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
be00: 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 string. Higher
be10: 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a layers in the.*
be20: 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d * SQLite stack m
be30: 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 ay generate inst
be40: 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 ances of this fi
be50: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a le control if.**
be60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 the [SQLITE_USE
be70: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f _FCNTL_TRACE] co
be80: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
be90: 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a n is enabled..**
bea0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
beb0: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 _FCNTL_HAS_MOVED
bec0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
bed0: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 E_FCNTL_HAS_MOVE
bee0: 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 D] file control
bef0: 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 interprets its a
bf00: 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 rgument as a.**
bf10: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
bf20: 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 teger and it wri
bf30: 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e tes a boolean in
bf40: 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 to that integer
bf50: 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 depending.** on
bf60: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
bf70: 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e he file has been
bf80: 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c renamed, moved,
bf90: 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 or deleted sinc
bfa0: 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 e it.** was firs
bfb0: 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 t opened..**.**
bfc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
bfd0: 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e TL_WIN32_GET_HAN
bfe0: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 DLE]].** The [SQ
bff0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 LITE_FCNTL_WIN32
c000: 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 _GET_HANDLE] opc
c010: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ode can be used
c020: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a to obtain the.**
c030: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 underlying nati
c040: 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 ve file handle a
c050: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 ssociated with a
c060: 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 file handle. T
c070: 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 his file.** cont
c080: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 rol interprets i
c090: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 ts argument as a
c0a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 pointer to a na
c0b0: 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 tive file handle
c0c0: 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 and.** writes t
c0d0: 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c he resulting val
c0e0: 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 ue there..**.**
c0f0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
c100: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e TL_WIN32_SET_HAN
c110: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 DLE]].** The [SQ
c120: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 LITE_FCNTL_WIN32
c130: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 _SET_HANDLE] opc
c140: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 ode is used for
c150: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 debugging. This
c160: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 .** opcode cause
c170: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 s the xFileContr
c180: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 ol method to swa
c190: 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c p the file handl
c1a0: 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a e with the one.*
c1b0: 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 * pointed to by
c1c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e the pArg argumen
c1d0: 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c t. This capabil
c1e0: 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69 ity is used duri
c1f0: 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e ng testing.** an
c200: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 d only needs to
c210: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 be supported whe
c220: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 n SQLITE_TEST is
c230: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 defined..**.**
c240: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
c250: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a TL_WAL_BLOCK]].*
c260: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
c270: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 NTL_WAL_BLOCK] i
c280: 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 s a signal to th
c290: 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 e VFS layer that
c2a0: 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 it might.** be
c2b0: 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 advantageous to
c2c0: 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 block on the nex
c2d0: 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 t WAL lock if th
c2e0: 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d e lock is not im
c2f0: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 mediately.** ava
c300: 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c ilable. The WAL
c310: 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 subsystem issue
c320: 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 s this signal du
c330: 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 ring rare.** cir
c340: 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 cumstances in or
c350: 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f der to fix a pro
c360: 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 blem with priori
c370: 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a ty inversion..**
c380: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 Applications sh
c390: 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d ould <em>not</em
c3a0: 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d > use this file-
c3b0: 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c control..**.** <
c3c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
c3d0: 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 L_ZIPVFS]].** Th
c3e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
c3f0: 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 ZIPVFS] opcode i
c400: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 s implemented by
c410: 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c zipvfs only. Al
c420: 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 l other.** VFS s
c430: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c hould return SQL
c440: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 ITE_NOTFOUND for
c450: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a this opcode..**
c460: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
c470: 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 _FCNTL_RBU]].**
c480: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
c490: 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 L_RBU] opcode is
c4a0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 implemented by
c4b0: 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 the special VFS
c4c0: 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 used by.** the R
c4d0: 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c BU extension onl
c4e0: 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 y. All other VF
c4f0: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 S should return
c500: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 SQLITE_NOTFOUND
c510: 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f for.** this opco
c520: 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e de. .**.** <li>
c530: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 [[SQLITE_FCNTL_B
c540: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 EGIN_ATOMIC_WRIT
c550: 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 E]].** If the [S
c560: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 QLITE_FCNTL_BEGI
c570: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 N_ATOMIC_WRITE]
c580: 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73 20 53 opcode returns S
c590: 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e 0a 2a QLITE_OK, then.*
c5a0: 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 * the file descr
c5b0: 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65 64 20 iptor is placed
c5c0: 69 6e 20 22 62 61 74 63 68 20 77 72 69 74 65 20 in "batch write
c5d0: 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a 2a 20 mode", which.**
c5e0: 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73 65 71 means all subseq
c5f0: 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61 uent write opera
c600: 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20 64 65 tions will be de
c610: 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e 65 0a ferred and done.
c620: 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20 61 74 ** atomically at
c630: 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c 49 54 the next [SQLIT
c640: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 E_FCNTL_COMMIT_A
c650: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20 20 53 TOMIC_WRITE]. S
c660: 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74 20 64 ystems.** that d
c670: 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 62 61 o not support ba
c680: 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69 74 65 tch atomic write
c690: 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 s will return SQ
c6a0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e 0a 2a LITE_NOTFOUND..*
c6b0: 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 73 * ^Following a s
c6c0: 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49 54 45 uccessful SQLITE
c6d0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f _FCNTL_BEGIN_ATO
c6e0: 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20 70 72 MIC_WRITE and pr
c6f0: 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6c ior to.** the cl
c700: 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 43 osing [SQLITE_FC
c710: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 NTL_COMMIT_ATOMI
c720: 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a 20 5b C_WRITE] or.** [
c730: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c SQLITE_FCNTL_ROL
c740: 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 LBACK_ATOMIC_WRI
c750: 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c TE], SQLite will
c760: 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 53 20 make.** no VFS
c770: 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 73 20 interface calls
c780: 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c on the same [sql
c790: 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c 65 20 ite3_file] file
c7a0: 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20 65 78 descriptor.** ex
c7b0: 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73 20 74 cept for calls t
c7c0: 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d 65 74 o the xWrite met
c7d0: 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46 69 6c hod and the xFil
c7e0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a eControl method.
c7f0: 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f ** with [SQLITE_
c800: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d FCNTL_SIZE_HINT]
c810: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
c820: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 LITE_FCNTL_COMMI
c830: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d T_ATOMIC_WRITE]]
c840: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
c850: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f FCNTL_COMMIT_ATO
c860: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 MIC_WRITE] opcod
c870: 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 e causes all wri
c880: 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 te.** operations
c890: 20 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 since the previ
c8a0: 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 ous successful c
c8b0: 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 all to .** [SQLI
c8c0: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 TE_FCNTL_BEGIN_A
c8d0: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 TOMIC_WRITE] to
c8e0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61 74 6f be performed ato
c8f0: 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 69 73 mically..** This
c900: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 file control re
c910: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
c920: 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 ] if and only if
c930: 20 74 68 65 20 77 72 69 74 65 73 20 77 65 72 65 the writes were
c940: 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72 6d 65 .** all performe
c950: 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 d successfully a
c960: 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63 6f 6d nd have been com
c970: 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73 69 73 mitted to persis
c980: 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a 2a 2a tent storage..**
c990: 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 ^Regardless of
c9a0: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 whether or not i
c9b0: 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 2c t is successful,
c9c0: 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 this file contr
c9d0: 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68 65 20 ol takes.** the
c9e0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 file descriptor
c9f0: 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 out of batch wri
ca00: 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61 74 20 te mode so that
ca10: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a all subsequent.*
ca20: 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f * write operatio
ca30: 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 ns are independe
ca40: 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 nt..** ^SQLite w
ca50: 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 ill never invoke
ca60: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f SQLITE_FCNTL_CO
ca70: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 MMIT_ATOMIC_WRIT
ca80: 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 E without.** a p
ca90: 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 rior successful
caa0: 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f call to [SQLITE_
cab0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d FCNTL_BEGIN_ATOM
cac0: 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a IC_WRITE]..**.**
cad0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
cae0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f NTL_ROLLBACK_ATO
caf0: 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 MIC_WRITE]].** T
cb00: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
cb10: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 _ROLLBACK_ATOMIC
cb20: 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 63 _WRITE] opcode c
cb30: 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65 0a auses all write.
cb40: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73 69 ** operations si
cb50: 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f 75 73 nce the previous
cb60: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
cb70: 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f to .** [SQLITE_
cb80: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d FCNTL_BEGIN_ATOM
cb90: 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65 20 IC_WRITE] to be
cba0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 rolled back..**
cbb0: 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 ^This file contr
cbc0: 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66 69 6c ol takes the fil
cbd0: 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75 74 e descriptor out
cbe0: 20 6f 66 20 62 61 74 63 68 20 77 72 69 74 65 20 of batch write
cbf0: 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61 74 20 mode.** so that
cc00: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77 all subsequent w
cc10: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 rite operations
cc20: 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e are independent.
cc30: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
cc40: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53 51 never invoke SQ
cc50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 LITE_FCNTL_ROLLB
cc60: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 ACK_ATOMIC_WRITE
cc70: 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72 without.** a pr
cc80: 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 ior successful c
cc90: 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46 all to [SQLITE_F
cca0: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 CNTL_BEGIN_ATOMI
ccb0: 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 C_WRITE]..**.**
ccc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
ccd0: 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 5d TL_LOCK_TIMEOUT]
cce0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
ccf0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 _FCNTL_LOCK_TIME
cd00: 4f 55 54 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 OUT] opcode caus
cd10: 65 73 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6f es attempts to o
cd20: 62 74 61 69 6e 0a 2a 2a 20 61 20 66 69 6c 65 20 btain.** a file
cd30: 6c 6f 63 6b 20 75 73 69 6e 67 20 74 68 65 20 78 lock using the x
cd40: 4c 6f 63 6b 20 6f 72 20 78 53 68 6d 4c 6f 63 6b Lock or xShmLock
cd50: 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20 methods of the
cd60: 56 46 53 20 74 6f 20 77 61 69 74 0a 2a 2a 20 66 VFS to wait.** f
cd70: 6f 72 20 75 70 20 74 6f 20 4d 20 6d 69 6c 6c 69 or up to M milli
cd80: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 66 seconds before f
cd90: 61 69 6c 69 6e 67 2c 20 77 68 65 72 65 20 4d 20 ailing, where M
cda0: 69 73 20 74 68 65 20 73 69 6e 67 6c 65 20 0a 2a is the single .*
cdb0: 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 * unsigned integ
cdc0: 65 72 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a er parameter..**
cdd0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </ul>.*/.#defin
cde0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c e SQLITE_FCNTL_L
cdf0: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 OCKSTATE
ce00: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
ce10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 SQLITE_FCNTL_GE
ce20: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
ce30: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
ce40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 SQLITE_FCNTL_SET
ce50: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 _LOCKPROXYFILE
ce60: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
ce70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 QLITE_FCNTL_LAST
ce80: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 _ERRNO
ce90: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
cea0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f LITE_FCNTL_SIZE_
ceb0: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 HINT
cec0: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 5.#define SQL
ced0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f ITE_FCNTL_CHUNK_
cee0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 SIZE
cef0: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 6.#define SQLI
cf00: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f TE_FCNTL_FILE_PO
cf10: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 INTER
cf20: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 7.#define SQLIT
cf30: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 E_FCNTL_SYNC_OMI
cf40: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 TTED
cf50: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
cf60: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f _FCNTL_WIN32_AV_
cf70: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 RETRY 9
cf80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
cf90: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 FCNTL_PERSIST_WA
cfa0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a L 10.
cfb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
cfc0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 CNTL_OVERWRITE
cfd0: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 11.#
cfe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
cff0: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 NTL_VFSNAME
d000: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 12.#d
d010: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
d020: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 TL_POWERSAFE_OVE
d030: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 RWRITE 13.#de
d040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
d050: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 L_PRAGMA
d060: 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 14.#def
d070: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
d080: 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 _BUSYHANDLER
d090: 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 15.#defi
d0a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
d0b0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 TEMPFILENAME
d0c0: 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 16.#defin
d0d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d e SQLITE_FCNTL_M
d0e0: 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 MAP_SIZE
d0f0: 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 18.#define
d100: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 SQLITE_FCNTL_TR
d110: 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ACE
d120: 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 19.#define
d130: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 SQLITE_FCNTL_HAS
d140: 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 _MOVED
d150: 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 20.#define S
d160: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 QLITE_FCNTL_SYNC
d170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
d180: 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 21.#define SQ
d190: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 LITE_FCNTL_COMMI
d1a0: 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 T_PHASETWO
d1b0: 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 22.#define SQL
d1c0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
d1d0: 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 SET_HANDLE
d1e0: 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 23.#define SQLI
d1f0: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f TE_FCNTL_WAL_BLO
d200: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CK
d210: 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 24.#define SQLIT
d220: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 E_FCNTL_ZIPVFS
d230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
d240: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
d250: 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 _FCNTL_RBU
d260: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 26
d270: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d280: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 FCNTL_VFS_POINTE
d290: 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a R 27.
d2a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
d2b0: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 CNTL_JOURNAL_POI
d2c0: 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 23 NTER 28.#
d2d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
d2e0: 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 NTL_WIN32_GET_HA
d2f0: 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23 64 NDLE 29.#d
d300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
d310: 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20 20 TL_PDB
d320: 20 20 20 20 20 20 20 20 20 20 33 30 0a 23 64 65 30.#de
d330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
d340: 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 L_BEGIN_ATOMIC_W
d350: 52 49 54 45 20 20 20 20 20 33 31 0a 23 64 65 66 RITE 31.#def
d360: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
d370: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 _COMMIT_ATOMIC_W
d380: 52 49 54 45 20 20 20 20 33 32 0a 23 64 65 66 69 RITE 32.#defi
d390: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
d3a0: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f ROLLBACK_ATOMIC_
d3b0: 57 52 49 54 45 20 20 33 33 0a 23 64 65 66 69 6e WRITE 33.#defin
d3c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c e SQLITE_FCNTL_L
d3d0: 4f 43 4b 5f 54 49 4d 45 4f 55 54 20 20 20 20 20 OCK_TIMEOUT
d3e0: 20 20 20 20 20 20 33 34 0a 0a 2f 2a 20 64 65 70 34../* dep
d3f0: 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f recated names */
d400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d410: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c GET_LOCKPROXYFIL
d420: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 E SQLITE_FC
d430: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 NTL_GET_LOCKPROX
d440: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 YFILE.#define SQ
d450: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f LITE_SET_LOCKPRO
d460: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 XYFILE SQLI
d470: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 TE_FCNTL_SET_LOC
d480: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 KPROXYFILE.#defi
d490: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 ne SQLITE_LAST_E
d4a0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 RRNO
d4b0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 SQLITE_FCNTL_LA
d4c0: 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a ST_ERRNO.../*.**
d4d0: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 CAPI3REF: Mutex
d4e0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 Handle.**.** Th
d4f0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 e mutex module w
d500: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 ithin SQLite def
d510: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 ines [sqlite3_mu
d520: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a tex] to be an.**
d530: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 abstract type f
d540: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 or a mutex objec
d550: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 t. The SQLite c
d560: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a ore never looks.
d570: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e ** at the intern
d580: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f al representatio
d590: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 n of an [sqlite3
d5a0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c _mutex]. It onl
d5b0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 y.** deals with
d5c0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 pointers to the
d5d0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 [sqlite3_mutex]
d5e0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 object..**.** Mu
d5f0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 texes are create
d600: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
d610: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e _mutex_alloc()].
d620: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
d630: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ct sqlite3_mutex
d640: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a sqlite3_mutex;.
d650: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
d660: 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 Loadable Extens
d670: 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 ion Thunk.**.**
d680: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 A pointer to the
d690: 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f opaque sqlite3_
d6a0: 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 api_routines str
d6b0: 75 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64 ucture is passed
d6c0: 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 as.** the third
d6d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e parameter to en
d6e0: 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c try points of [l
d6f0: 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f oadable extensio
d700: 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 ns]. This.** st
d710: 72 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 ructure must be
d720: 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 typedefed in ord
d730: 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e er to work aroun
d740: 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 d compiler warni
d750: 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 ngs.** on some p
d760: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 latforms..*/.typ
d770: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
d780: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 te3_api_routines
d790: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 sqlite3_api_rou
d7a0: 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tines;../*.** CA
d7b0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
d7c0: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a face Object.**.*
d7d0: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
d7e0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
d7f0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 object defines
d800: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 the interface be
d810: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c tween.** the SQL
d820: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 ite core and the
d830: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 underlying oper
d840: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 ating system. T
d850: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 he "vfs".** in t
d860: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f he name of the o
d870: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 bject stands for
d880: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 "virtual file s
d890: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 ystem". See.**
d8a0: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 the [VFS | VFS d
d8b0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f ocumentation] fo
d8c0: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d r further inform
d8d0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ation..**.** The
d8e0: 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 20 69 VFS interface i
d8f0: 73 20 73 6f 6d 65 74 69 6d 65 73 20 65 78 74 65 s sometimes exte
d900: 6e 64 65 64 20 62 79 20 61 64 64 69 6e 67 20 6e nded by adding n
d910: 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74 6f 0a ew methods onto.
d920: 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20 45 61 63 ** the end. Eac
d930: 68 20 74 69 6d 65 20 73 75 63 68 20 61 6e 20 65 h time such an e
d940: 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72 73 2c xtension occurs,
d950: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 the iVersion fi
d960: 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72 65 6d eld.** is increm
d970: 65 6e 74 65 64 2e 20 20 54 68 65 20 69 56 65 72 ented. The iVer
d980: 73 69 6f 6e 20 76 61 6c 75 65 20 73 74 61 72 74 sion value start
d990: 65 64 20 6f 75 74 20 61 73 20 31 20 69 6e 0a 2a ed out as 1 in.*
d9a0: 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f * SQLite [versio
d9b0: 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64 61 74 n 3.5.0] on [dat
d9c0: 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68 65 6e eof:3.5.0], then
d9d0: 20 69 6e 63 72 65 61 73 65 64 20 74 6f 20 32 0a increased to 2.
d9e0: 2a 2a 20 77 69 74 68 20 53 51 4c 69 74 65 20 5b ** with SQLite [
d9f0: 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d 20 6f version 3.7.0] o
da00: 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 30 5d n [dateof:3.7.0]
da10: 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e 63 72 65 , and then incre
da20: 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77 69 74 ased.** to 3 wit
da30: 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f h SQLite [versio
da40: 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64 61 74 n 3.7.6] on [dat
da50: 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41 64 64 eof:3.7.6]. Add
da60: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a itional fields.*
da70: 2a 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 * may be appende
da80: 64 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 d to the sqlite3
da90: 5f 76 66 73 20 6f 62 6a 65 63 74 20 61 6e 64 20 _vfs object and
daa0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c the iVersion val
dab0: 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72 65 61 ue.** may increa
dac0: 73 65 20 61 67 61 69 6e 20 69 6e 20 66 75 74 75 se again in futu
dad0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
dae0: 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 QLite..** Note t
daf0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 hat the structur
db00: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 e.** of the sqli
db10: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 te3_vfs object c
db20: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 hanges in the tr
db30: 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a ansition from.**
db40: 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e SQLite [version
db50: 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65 72 73 3.5.9] to [vers
db60: 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20 5b 64 ion 3.6.0] on [d
db70: 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a 2a 20 ateof:3.6.0].**
db80: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 and yet the iVer
db90: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e sion field was n
dba0: 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a ot modified..**.
dbb0: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 ** The szOsFile
dbc0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a field is the siz
dbd0: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 e of the subclas
dbe0: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c sed [sqlite3_fil
dbf0: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 e].** structure
dc00: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 used by this VFS
dc10: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 . mxPathname is
dc20: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e the maximum len
dc30: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 gth of.** a path
dc40: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 name in this VFS
dc50: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 ..**.** Register
dc60: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f ed sqlite3_vfs o
dc70: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 bjects are kept
dc80: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 on a linked list
dc90: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 formed by.** th
dca0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
dcb0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 The [sqlite3_v
dcc0: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a fs_register()].*
dcd0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 * and [sqlite3_v
dce0: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d fs_unregister()]
dcf0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 interfaces mana
dd00: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 ge this list.**
dd10: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 in a thread-safe
dd20: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 way. The [sqli
dd30: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 te3_vfs_find()]
dd40: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 interface.** sea
dd50: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 rches the list.
dd60: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 Neither the app
dd70: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f lication code no
dd80: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 r the VFS.** imp
dd90: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 lementation shou
dda0: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 ld use the pNext
ddb0: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
ddc0: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 The pNext field
ddd0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c is the only fiel
dde0: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 d in the sqlite3
ddf0: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 _vfs.** structur
de00: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 e that SQLite wi
de10: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 ll ever modify.
de20: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c SQLite will onl
de30: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d y access.** or m
de40: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 odify this field
de50: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 while holding a
de60: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 particular stat
de70: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 ic mutex..** The
de80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
de90: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 uld never modify
dea0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e anything within
deb0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
dec0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 .** object once
ded0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 the object has b
dee0: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a een registered..
def0: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 **.** The zName
df00: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 field holds the
df10: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 name of the VFS
df20: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d module. The nam
df30: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 e must.** be uni
df40: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 que across all V
df50: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a FS modules..**.*
df60: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e * [[sqlite3_vfs.
df70: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 xOpen]].** ^SQLi
df80: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 te guarantees th
df90: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 at the zFilename
dfa0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f parameter to xO
dfb0: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 pen.** is either
dfc0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
dfd0: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e or string obtain
dfe0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c ed.** from xFull
dff0: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 Pathname() with
e000: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 an optional suff
e010: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 ix added..** ^If
e020: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 a suffix is add
e030: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e ed to the zFilen
e040: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 ame parameter, i
e050: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 t will.** consis
e060: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d t of a single "-
e070: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c " character foll
e080: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 owed by no more
e090: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 than.** 11 alpha
e0a0: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 numeric and/or "
e0b0: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a -" characters..*
e0c0: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 * ^SQLite furthe
e0d0: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 r guarantees tha
e0e0: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 t.** the string
e0f0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e will be valid an
e100: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 d unchanged unti
e110: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a l xClose() is.**
e120: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 called. Because
e130: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 of the previous
e140: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 sentence,.** th
e150: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d e [sqlite3_file]
e160: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 can safely stor
e170: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 e a pointer to t
e180: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 he.** filename i
e190: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 f it needs to re
e1a0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e member the filen
e1b0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 ame for some rea
e1c0: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a son..** If the z
e1d0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
e1e0: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 er to xOpen is a
e1f0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
e200: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 en xOpen.** must
e210: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 invent its own
e220: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 temporary name f
e230: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 or the file. ^W
e240: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 henever the .**
e250: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 xFilename parame
e260: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 ter is NULL it w
e270: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 ill also be the
e280: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a case that the.**
e290: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
e2a0: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 will include [S
e2b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
e2c0: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a EONCLOSE]..**.**
e2d0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d The flags argum
e2e0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 ent to xOpen() i
e2f0: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 ncludes all bits
e300: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 set in.** the f
e310: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
e320: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
e330: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 2()]. Or if [sq
e340: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a lite3_open()].**
e350: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 or [sqlite3_ope
e360: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 n16()] is used,
e370: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 then flags inclu
e380: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 des at least.**
e390: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
e3a0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 DWRITE] | [SQLIT
e3b0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 E_OPEN_CREATE].
e3c0: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f .** If xOpen() o
e3d0: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 pens a file read
e3e0: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 -only then it se
e3f0: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f ts *pOutFlags to
e400: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c .** include [SQL
e410: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
e420: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 Y]. Other bits
e430: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 in *pOutFlags ma
e440: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 y be set..**.**
e450: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c ^(SQLite will al
e460: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 so add one of th
e470: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 e following flag
e480: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 s to the xOpen()
e490: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 .** call, depend
e4a0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 ing on the objec
e4b0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a t being opened:.
e4c0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
e4d0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
e4e0: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 _MAIN_DB].** <li
e4f0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
e500: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a MAIN_JOURNAL].**
e510: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
e520: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 PEN_TEMP_DB].**
e530: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
e540: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d EN_TEMP_JOURNAL]
e550: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
e560: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 E_OPEN_TRANSIENT
e570: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
e580: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f QLITE_OPEN_SUBJO
e590: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 URNAL].** <li>
e5a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 [SQLITE_OPEN_MAS
e5b0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 TER_JOURNAL].**
e5c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
e5d0: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e EN_WAL].** </ul>
e5e0: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c )^.**.** The fil
e5f0: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 e I/O implementa
e600: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 tion can use the
e610: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 object type fla
e620: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 gs to.** change
e630: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 the way it deals
e640: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f with files. Fo
e650: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 r example, an ap
e660: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 plication.** tha
e670: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 t does not care
e680: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f about crash reco
e690: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b very or rollback
e6a0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 might make.** t
e6b0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 he open of a jou
e6c0: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f rnal file a no-o
e6d0: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 p. Writes to th
e6e0: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 is journal would
e6f0: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f .** also be no-o
e700: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 ps, and any atte
e710: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 mpt to read the
e720: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 journal would re
e730: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 turn.** SQLITE_I
e740: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d OERR. Or the im
e750: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 plementation mig
e760: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 ht recognize tha
e770: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 t a database.**
e780: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 file will be doi
e790: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 ng page-aligned
e7a0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 sector reads and
e7b0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e writes in a ran
e7c0: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 dom.** order and
e7d0: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 set up its I/O
e7e0: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 subsystem accord
e7f0: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c ingly..**.** SQL
e800: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 ite might also a
e810: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f dd one of the fo
e820: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f llowing flags to
e830: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f the xOpen metho
e840: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a d:.**.** <ul>.**
e850: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
e860: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
e870: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
e880: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 E_OPEN_EXCLUSIVE
e890: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a ].** </ul>.**.**
e8a0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 The [SQLITE_OPE
e8b0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
e8c0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 flag means the
e8d0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a file should be.*
e8e0: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 * deleted when i
e8f0: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 t is closed. ^T
e900: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
e910: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a DELETEONCLOSE].*
e920: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f * will be set fo
e930: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 r TEMP databases
e940: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e and their journ
e950: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a als, transient.*
e960: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 * databases, and
e970: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a subjournals..**
e980: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
e990: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d _OPEN_EXCLUSIVE]
e9a0: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 flag is always
e9b0: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 used in conjunct
e9c0: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ion.** with the
e9d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 [SQLITE_OPEN_CRE
e9e0: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 ATE] flag, which
e9f0: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 are both direct
ea00: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 ly.** analogous
ea10: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e to the O_EXCL an
ea20: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 d O_CREAT flags
ea30: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 of the POSIX ope
ea40: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 n().** API. The
ea50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 SQLITE_OPEN_EXC
ea60: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 LUSIVE flag, whe
ea70: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 n paired with th
ea80: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 e .** SQLITE_OPE
ea90: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 N_CREATE, is use
eaa0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 d to indicate th
eab0: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 at file should a
eac0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 lways.** be crea
ead0: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 ted, and that it
eae0: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 is an error if
eaf0: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 it already exist
eb00: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e s..** It is <i>n
eb10: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 ot</i> used to i
eb20: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 ndicate the file
eb30: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 should be opene
eb40: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 d .** for exclus
eb50: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a ive access..**.*
eb60: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 * ^At least szOs
eb70: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 File bytes of me
eb80: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 mory are allocat
eb90: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 ed by SQLite.**
eba0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 to hold the [sq
ebb0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 lite3_file] stru
ebc0: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 cture passed as
ebd0: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 the third.** arg
ebe0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 ument to xOpen.
ebf0: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f The xOpen metho
ec00: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 d does not have
ec10: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 to.** allocate t
ec20: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 he structure; it
ec30: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c should just fil
ec40: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 l it in. Note t
ec50: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e hat.** the xOpen
ec60: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 method must set
ec70: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c the sqlite3_fil
ec80: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 e.pMethods to ei
ec90: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 ther.** a valid
eca0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
ecb0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 ods] object or t
ecc0: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d o NULL. xOpen m
ecd0: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 ust do.** this e
ece0: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 ven if the open
ecf0: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 fails. SQLite e
ed00: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 xpects that the
ed10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 sqlite3_file.pMe
ed20: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 thods.** element
ed30: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 will be valid a
ed40: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 fter xOpen retur
ed50: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ns regardless of
ed60: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 the success.**
ed70: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 or failure of th
ed80: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a e xOpen call..**
ed90: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 .** [[sqlite3_vf
eda0: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e s.xAccess]].** ^
edb0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 The flags argume
edc0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 nt to xAccess()
edd0: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 may be [SQLITE_A
ede0: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a CCESS_EXISTS].**
edf0: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 to test for the
ee00: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 existence of a
ee10: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 file, or [SQLITE
ee20: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
ee30: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 E] to.** test wh
ee40: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 ether a file is
ee50: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 readable and wri
ee60: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 table, or [SQLIT
ee70: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a E_ACCESS_READ].*
ee80: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 * to test whethe
ee90: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c r a file is at l
eea0: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 east readable.
eeb0: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 The file can be
eec0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e a.** directory.
eed0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 .**.** ^SQLite w
eee0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 ill always alloc
eef0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 ate at least mxP
ef00: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 athname+1 bytes
ef10: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 for the.** outpu
ef20: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 t buffer xFullPa
ef30: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 thname. The exa
ef40: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f ct size of the o
ef50: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 utput buffer.**
ef60: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 is also passed a
ef70: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f s a parameter to
ef80: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 both methods.
ef90: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 If the output bu
efa0: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c ffer.** is not l
efb0: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 arge enough, [SQ
efc0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 LITE_CANTOPEN] s
efd0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 hould be returne
efe0: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 d. Since this is
eff0: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 .** handled as a
f000: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 fatal error by
f010: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c SQLite, vfs impl
f020: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 ementations shou
f030: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 ld endeavor.** t
f040: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 o prevent this b
f050: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 y setting mxPath
f060: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 name to a suffic
f070: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c iently large val
f080: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 ue..**.** The xR
f090: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c andomness(), xSl
f0a0: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 eep(), xCurrentT
f0b0: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 ime(), and xCurr
f0c0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a entTimeInt64().*
f0d0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 * interfaces are
f0e0: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 not strictly a
f0f0: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 part of the file
f100: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 system, but they
f110: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 are.** included
f120: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 in the VFS stru
f130: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 cture for comple
f140: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 teness..** The x
f150: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e Randomness() fun
f160: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 ction attempts t
f170: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 o return nBytes
f180: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 bytes.** of good
f190: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e -quality randomn
f1a0: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 ess into zOut.
f1b0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 The return value
f1c0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 is.** the actua
f1d0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 l number of byte
f1e0: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 s of randomness
f1f0: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 obtained..** The
f200: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 xSleep() method
f210: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c causes the call
f220: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c ing thread to sl
f230: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 eep for at.** le
f240: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ast the number o
f250: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 f microseconds g
f260: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 iven. ^The xCur
f270: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 rentTime().** me
f280: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a thod returns a J
f290: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 ulian Day Number
f2a0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 for the current
f2b0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 date and time a
f2c0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 s.** a floating
f2d0: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 point value..**
f2e0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d ^The xCurrentTim
f2f0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 eInt64() method
f300: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 returns, as an i
f310: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 nteger, the Juli
f320: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 an.** Day Number
f330: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 multiplied by 8
f340: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 6400000 (the num
f350: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f ber of milliseco
f360: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d nds in .** a 24-
f370: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 hour day). .**
f380: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 ^SQLite will use
f390: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d the xCurrentTim
f3a0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 eInt64() method
f3b0: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 to get the curre
f3c0: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 nt.** date and t
f3d0: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 ime if that meth
f3e0: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 od is available
f3f0: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 (if iVersion is
f400: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 2 or .** greater
f410: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f and the functio
f420: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 n pointer is not
f430: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 NULL) and will
f440: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 fall back.** to
f450: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 xCurrentTime() i
f460: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e f xCurrentTimeIn
f470: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c t64() is unavail
f480: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 able..**.** ^The
f490: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 xSetSystemCall(
f4a0: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c ), xGetSystemCal
f4b0: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 l(), and xNestSy
f4c0: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 stemCall() inter
f4d0: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 faces.** are not
f4e0: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c used by the SQL
f4f0: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 ite core. These
f500: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 optional interf
f510: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 aces are provide
f520: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 d.** by some VFS
f530: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 es to facilitate
f540: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 testing of the
f550: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 VFS code. By ove
f560: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 rriding .** syst
f570: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 em calls with fu
f580: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 nctions under it
f590: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 s control, a tes
f5a0: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a t program can.**
f5b0: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 simulate faults
f5c0: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 and error condi
f5d0: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 tions that would
f5e0: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 otherwise be di
f5f0: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d fficult.** or im
f600: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 possible to indu
f610: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 ce. The set of
f620: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 system calls tha
f630: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 t can be overrid
f640: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 den.** varies fr
f650: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e om one VFS to an
f660: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 other, and from
f670: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 one version of t
f680: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 he same VFS to t
f690: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 he.** next. App
f6a0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 lications that u
f6b0: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 se these interfa
f6c0: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 ces must be prep
f6d0: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 ared for any.**
f6e0: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 or all of these
f6f0: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 interfaces to be
f700: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 NULL or for the
f710: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 ir behavior to c
f720: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e hange.** from on
f730: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 e release to the
f740: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 next. Applicat
f750: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 ions must not at
f760: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a tempt to access.
f770: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 ** any of these
f780: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 methods if the i
f790: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 Version of the V
f7a0: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 FS is less than
f7b0: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 3..*/.typedef st
f7c0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 ruct sqlite3_vfs
f7d0: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 sqlite3_vfs;.ty
f7e0: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c pedef void (*sql
f7f0: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 ite3_syscall_ptr
f800: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 )(void);.struct
f810: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 sqlite3_vfs {.
f820: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 int iVersion;
f830: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 /* Stru
f840: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 cture version nu
f850: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 mber (currently
f860: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 3) */. int szOs
f870: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 File;
f880: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 /* Size of subc
f890: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 lassed sqlite3_f
f8a0: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 ile */. int mxP
f8b0: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 athname;
f8c0: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c /* Maximum fil
f8d0: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 e pathname lengt
f8e0: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 h */. sqlite3_v
f8f0: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 fs *pNext;
f900: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 /* Next register
f910: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 ed VFS */. cons
f920: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 t char *zName;
f930: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
f940: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c this virtual fil
f950: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f e system */. vo
f960: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 id *pAppData;
f970: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 /* Pointe
f980: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e r to application
f990: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a -specific data *
f9a0: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 /. int (*xOpen)
f9b0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
f9c0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
f9d0: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c , sqlite3_file*,
f9e0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
f9f0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a int flags, int *
fa00: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e pOutFlags);. in
fa10: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c t (*xDelete)(sql
fa20: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
fa30: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
fa40: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e t syncDir);. in
fa50: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c t (*xAccess)(sql
fa60: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
fa70: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
fa80: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 t flags, int *pR
fa90: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a esOut);. int (*
faa0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 xFullPathname)(s
fab0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
fac0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
fad0: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a int nOut, char *
fae0: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 zOut);. void *(
faf0: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 *xDlOpen)(sqlite
fb00: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
fb10: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a ar *zFilename);.
fb20: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f void (*xDlErro
fb30: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c r)(sqlite3_vfs*,
fb40: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 int nByte, char
fb50: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f *zErrMsg);. vo
fb60: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 id (*(*xDlSym)(s
fb70: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 qlite3_vfs*,void
fb80: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
fb90: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a Symbol))(void);.
fba0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 void (*xDlClos
fbb0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
fbc0: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 void*);. int (
fbd0: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 *xRandomness)(sq
fbe0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 lite3_vfs*, int
fbf0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 nByte, char *zOu
fc00: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 t);. int (*xSle
fc10: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ep)(sqlite3_vfs*
fc20: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e , int microsecon
fc30: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 ds);. int (*xCu
fc40: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 rrentTime)(sqlit
fc50: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a e3_vfs*, double*
fc60: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c );. int (*xGetL
fc70: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 astError)(sqlite
fc80: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 3_vfs*, int, cha
fc90: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 r *);. /*. **
fca0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
fcb0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
fcc0: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 1 of the sqlite
fcd0: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a _vfs object. **
fce0: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 definition. Th
fcf0: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 ose that follow
fd00: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 are added in ver
fd10: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a sion 2 or later.
fd20: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 */. int (*xCu
fd30: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 rrentTimeInt64)(
fd40: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 sqlite3_vfs*, sq
fd50: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 lite3_int64*);.
fd60: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 /*. ** The met
fd70: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 hods above are i
fd80: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 n versions 1 and
fd90: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 2 of the sqlite
fda0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a _vfs object.. *
fdb0: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 * Those below ar
fdc0: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 e for version 3
fdd0: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a and greater.. *
fde0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 /. int (*xSetSy
fdf0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 stemCall)(sqlite
fe00: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
fe10: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 ar *zName, sqlit
fe20: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b e3_syscall_ptr);
fe30: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 . sqlite3_sysca
fe40: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 ll_ptr (*xGetSys
fe50: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 temCall)(sqlite3
fe60: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
fe70: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e r *zName);. con
fe80: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 st char *(*xNext
fe90: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 SystemCall)(sqli
fea0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
feb0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 char *zName);.
fec0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 /*. ** The meth
fed0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e ods above are in
fee0: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f versions 1 thro
fef0: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c ugh 3 of the sql
ff00: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a ite_vfs object..
ff10: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 ** New fields
ff20: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 may be appended
ff30: 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f in future versio
ff40: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f ns. The iVersio
ff50: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c n. ** value wil
ff60: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e l increment when
ff70: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e ever this happen
ff80: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a s. . */.};../*.
ff90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 ** CAPI3REF: Fla
ffa0: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 gs for the xAcce
ffb0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a ss VFS method.**
ffc0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 .** These intege
ffd0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 r constants can
ffe0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 be used as the t
fff0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
10000 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 o.** the xAccess
10010 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 method of an [s
10020 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
10030 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d ct. They determ
10040 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 ine.** what kind
10050 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 of permissions
10060 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
10070 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f od is looking fo
10080 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 r..** With SQLIT
10090 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c E_ACCESS_EXISTS,
100a0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
100b0 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 hod.** simply ch
100c0 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 ecks whether the
100d0 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a file exists..**
100e0 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 With SQLITE_ACC
100f0 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 ESS_READWRITE, t
10100 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
10110 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 d.** checks whet
10120 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 her the named di
10130 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 rectory is both
10140 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 readable and wri
10150 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 table.** (in oth
10160 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c er words, if fil
10170 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c es can be added,
10180 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 removed, and re
10190 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 named within.**
101a0 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a the directory)..
101b0 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 ** The SQLITE_AC
101c0 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 CESS_READWRITE c
101d0 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 onstant is curre
101e0 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 ntly used only b
101f0 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 y the.** [temp_s
10200 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 tore_directory p
10210 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 ragma], though t
10220 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 his could change
10230 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 in a future.**
10240 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
10250 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 e..** With SQLIT
10260 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 E_ACCESS_READ, t
10270 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
10280 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 d.** checks whet
10290 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 her the file is
102a0 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 readable. The S
102b0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
102c0 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a D constant is.**
102d0 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 currently unuse
102e0 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 d, though it mig
102f0 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 ht be used in a
10300 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
10310 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a f.** SQLite..*/.
10320 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
10330 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 CCESS_EXISTS
10340 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
10350 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
10360 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 E 1 /* Used by
10370 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f PRAGMA temp_sto
10380 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a re_directory */.
10390 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
103a0 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 CCESS_READ
103b0 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 2 /* Unused */
103c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
103d0 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 : Flags for the
103e0 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 xShmLock VFS met
103f0 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 hod.**.** These
10400 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
10410 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 s define the var
10420 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 ious locking ope
10430 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 rations.** allow
10440 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f ed by the xShmLo
10450 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 ck method of [sq
10460 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
10470 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f ]. The.** follo
10480 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c wing are the onl
10490 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 y legal combinat
104a0 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f ions of flags to
104b0 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b the.** xShmLock
104c0 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c method:.**.** <
104d0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c ul>.** <li> SQL
104e0 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 ITE_SHM_LOCK | S
104f0 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 QLITE_SHM_SHARED
10500 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
10510 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 _SHM_LOCK | SQLI
10520 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
10530 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
10540 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 _SHM_UNLOCK | SQ
10550 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a LITE_SHM_SHARED.
10560 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
10570 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c SHM_UNLOCK | SQL
10580 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 ITE_SHM_EXCLUSIV
10590 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a E.** </ul>.**.**
105a0 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c When unlocking,
105b0 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 the same SHARED
105c0 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c or EXCLUSIVE fl
105d0 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c ag must be suppl
105e0 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 ied as.** was gi
105f0 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 ven on the corre
10600 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 sponding lock.
10610 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c .**.** The xShmL
10620 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 ock method can t
10630 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 ransition betwee
10640 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 n unlocked and S
10650 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 HARED or.** betw
10660 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 een unlocked and
10670 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 EXCLUSIVE. It
10680 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f cannot transitio
10690 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 n between SHARED
106a0 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 .** and EXCLUSIV
106b0 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 E..*/.#define SQ
106c0 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 LITE_SHM_UNLOCK
106d0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
106e0 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 SQLITE_SHM_LOCK
106f0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
10700 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 e SQLITE_SHM_SHA
10710 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 RED 4.#def
10720 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 ine SQLITE_SHM_E
10730 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f XCLUSIVE 8../
10740 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
10750 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 aximum xShmLock
10760 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 index.**.** The
10770 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 xShmLock method
10780 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d on [sqlite3_io_m
10790 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 ethods] may use
107a0 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 values.** betwee
107b0 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 n 0 and this upp
107c0 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 er bound as its
107d0 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e "offset" argumen
107e0 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 t..** The SQLite
107f0 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 core will never
10800 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 attempt to acqu
10810 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 ire or release a
10820 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 .** lock outside
10830 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a of this range.*
10840 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
10850 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 _SHM_NLOCK
10860 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 8.../*.** CAPI
10870 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 3REF: Initialize
10880 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 The SQLite Libr
10890 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ary.**.** ^The s
108a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
108b0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 e() routine init
108c0 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 ializes the.** S
108d0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 QLite library.
108e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 ^The sqlite3_shu
108f0 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a tdown() routine.
10900 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 ** deallocates a
10910 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 ny resources tha
10920 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 t were allocated
10930 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 by sqlite3_init
10940 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 ialize()..** The
10950 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
10960 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 designed to aid
10970 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 in process initi
10980 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a alization and.**
10990 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 shutdown on emb
109a0 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 edded systems.
109b0 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c Workstation appl
109c0 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a ications using.*
109d0 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c * SQLite normall
109e0 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f y do not need to
109f0 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f invoke either o
10a00 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
10a10 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 ..**.** A call t
10a20 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 o sqlite3_initia
10a30 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 lize() is an "ef
10a40 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 fective" call if
10a50 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 it is.** the fi
10a60 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 rst time sqlite3
10a70 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
10a80 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 invoked during
10a90 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a the lifetime of.
10aa0 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 ** the process,
10ab0 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 or if it is the
10ac0 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 first time sqlit
10ad0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
10ae0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f is invoked.** fo
10af0 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 llowing a call t
10b00 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
10b10 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e wn(). ^(Only an
10b20 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a effective call.
10b30 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e ** of sqlite3_in
10b40 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 itialize() does
10b50 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 any initializati
10b60 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 on. All other c
10b70 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d alls.** are harm
10b80 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a less no-ops.)^.*
10b90 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 *.** A call to s
10ba0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
10bb0 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 ) is an "effecti
10bc0 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 ve" call if it i
10bd0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 s the first.** c
10be0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
10bf0 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 hutdown() since
10c00 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 the last sqlite3
10c10 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 _initialize().
10c20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 ^(Only.** an eff
10c30 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 ective call to s
10c40 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
10c50 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 ) does any deini
10c60 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 tialization..**
10c70 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 All other valid
10c80 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
10c90 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 _shutdown() are
10ca0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e harmless no-ops.
10cb0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )^.**.** The sql
10cc0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
10cd0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 ) interface is t
10ce0 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 hreadsafe, but s
10cf0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
10d00 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 ).** is not. Th
10d10 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f e sqlite3_shutdo
10d20 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d wn() interface m
10d30 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c ust only be call
10d40 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e ed from a.** sin
10d50 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c gle thread. All
10d60 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 open [database
10d70 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 connections] mus
10d80 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 t be closed and
10d90 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c all.** other SQL
10da0 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 ite resources mu
10db0 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 st be deallocate
10dc0 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b d prior to invok
10dd0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 ing.** sqlite3_s
10de0 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a hutdown()..**.**
10df0 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 Among other thi
10e00 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e ngs, ^sqlite3_in
10e10 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 itialize() will
10e20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 invoke.** sqlite
10e30 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 3_os_init(). Si
10e40 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 milarly, ^sqlite
10e50 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 3_shutdown().**
10e60 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 will invoke sqli
10e70 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a te3_os_end()..**
10e80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
10e90 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f _initialize() ro
10ea0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 utine returns [S
10eb0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
10ec0 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 cess..** ^If for
10ed0 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 some reason, sq
10ee0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
10ef0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 () is unable to
10f00 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 initialize.** th
10f10 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 e library (perha
10f20 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 ps it is unable
10f30 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 to allocate a ne
10f40 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 eded resource su
10f50 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 ch.** as a mutex
10f60 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 ) it returns an
10f70 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 [error code] oth
10f80 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
10f90 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 OK]..**.** ^The
10fa0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
10fb0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 ze() routine is
10fc0 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c called internall
10fd0 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a y by many other.
10fe0 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ** SQLite interf
10ff0 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 aces so that an
11000 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 application usua
11010 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 lly does not nee
11020 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 d to.** invoke s
11030 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
11040 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 e() directly. F
11050 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c or example, [sql
11060 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 ite3_open()].**
11070 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e calls sqlite3_in
11080 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 itialize() so th
11090 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
110a0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 will be automat
110b0 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 ically.** initia
110c0 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 lized when [sqli
110d0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 te3_open()] is c
110e0 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 alled if it has
110f0 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a not be initializ
11100 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 ed.** already.
11110 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c ^However, if SQL
11120 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
11130 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 with the [SQLITE
11140 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a _OMIT_AUTOINIT].
11150 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 ** compile-time
11160 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 option, then the
11170 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 automatic calls
11180 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 to sqlite3_init
11190 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 ialize().** are
111a0 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 omitted and the
111b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
111c0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e call sqlite3_in
111d0 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 itialize() direc
111e0 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 tly.** prior to
111f0 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 using any other
11200 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
11210 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 . For maximum p
11220 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 ortability,.** i
11230 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 t is recommended
11240 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f that applicatio
11250 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 ns always invoke
11260 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
11270 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c ize().** directl
11280 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 y prior to using
11290 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 any other SQLit
112a0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 e interface. Fu
112b0 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a ture releases.**
112c0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 of SQLite may r
112d0 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e equire this. In
112e0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
112f0 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 e behavior exhib
11300 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c ited.** when SQL
11310 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
11320 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 with [SQLITE_OMI
11330 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 T_AUTOINIT] migh
11340 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 t become the.**
11350 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 default behavior
11360 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 in some future
11370 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
11380 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e..**.** The sql
11390 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 ite3_os_init() r
113a0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 outine does oper
113b0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 ating-system spe
113c0 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c cific.** initial
113d0 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 ization of the S
113e0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 QLite library.
113f0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 The sqlite3_os_e
11400 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 nd().** routine
11410 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 undoes the effec
11420 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f t of sqlite3_os_
11430 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c init(). Typical
11440 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 tasks.** perfor
11450 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 med by these rou
11460 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c tines include al
11470 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c location or deal
11480 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 location.** of s
11490 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c tatic resources,
114a0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
114b0 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 of global variab
114c0 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 les,.** setting
114d0 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 up a default [sq
114e0 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c lite3_vfs] modul
114f0 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 e, or setting up
11500 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f .** a default co
11510 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e nfiguration usin
11520 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 g [sqlite3_confi
11530 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 g()]..**.** The
11540 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
11550 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 ld never invoke
11560 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f either sqlite3_o
11570 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 s_init().** or s
11580 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 qlite3_os_end()
11590 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 directly. The a
115a0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
115b0 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a d only invoke.**
115c0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
115d0 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ize() and sqlite
115e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 3_shutdown(). T
115f0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e he sqlite3_os_in
11600 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 it().** interfac
11610 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f e is called auto
11620 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c matically by sql
11630 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
11640 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ) and.** sqlite3
11650 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c _os_end() is cal
11660 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 led by sqlite3_s
11670 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 hutdown(). Appr
11680 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 opriate.** imple
11690 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 mentations for s
116a0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
116b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f and sqlite3_os_
116c0 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 end().** are bui
116d0 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 lt into SQLite w
116e0 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c hen it is compil
116f0 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e ed for Unix, Win
11700 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a dows, or OS/2..*
11710 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 * When [custom b
11720 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f uilds | built fo
11730 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d r other platform
11740 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 s].** (using the
11750 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 [SQLITE_OS_OTHE
11760 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d R=1] compile-tim
11770 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 e.** option) the
11780 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
11790 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 t supply a suita
117a0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
117b0 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 on for.** sqlite
117c0 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 3_os_init() and
117d0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
117e0 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f . An applicatio
117f0 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d n-supplied.** im
11800 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
11810 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
11820 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f ) or sqlite3_os_
11830 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 end().** must re
11840 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
11850 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 on success and
11860 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f some other [erro
11870 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 r code] upon.**
11880 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 failure..*/.int
11890 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
118a0 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 ze(void);.int sq
118b0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 lite3_shutdown(v
118c0 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 oid);.int sqlite
118d0 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 3_os_init(void);
118e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f .int sqlite3_os_
118f0 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a end(void);../*.*
11900 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
11910 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 iguring The SQLi
11920 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a te Library.**.**
11930 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e The sqlite3_con
11940 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
11950 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 is used to make
11960 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 global configura
11970 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 tion.** changes
11980 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 to SQLite in ord
11990 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 er to tune SQLit
119a0 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 e to the specifi
119b0 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 c needs of.** th
119c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 e application.
119d0 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 The default conf
119e0 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 iguration is rec
119f0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 ommended for mos
11a00 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e t.** application
11a10 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f s and so this ro
11a20 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 utine is usually
11a30 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 not necessary.
11a40 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 It is.** provid
11a50 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 ed to support ra
11a60 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 re applications
11a70 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 with unusual nee
11a80 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 ds..**.** <b>The
11a90 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
11aa0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e ) interface is n
11ab0 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 ot threadsafe. T
11ac0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a he application.*
11ad0 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 * must ensure th
11ae0 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 at no other SQLi
11af0 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 te interfaces ar
11b00 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 e invoked by oth
11b10 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 er.** threads wh
11b20 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ile sqlite3_conf
11b30 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e ig() is running.
11b40 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 </b>.**.** The s
11b50 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
11b60 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 interface.** may
11b70 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 only be invoked
11b80 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 prior to librar
11b90 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e y initialization
11ba0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
11bb0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
11bc0 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f or after shutdo
11bd0 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 wn by [sqlite3_s
11be0 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e hutdown()]..** ^
11bf0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 If sqlite3_confi
11c00 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 g() is called af
11c10 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 ter [sqlite3_ini
11c20 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 tialize()] and b
11c30 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 efore.** [sqlite
11c40 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 3_shutdown()] th
11c50 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 en it will retur
11c60 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e n SQLITE_MISUSE.
11c70 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 .** Note, howeve
11c80 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 r, that ^sqlite3
11c90 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 _config() can be
11ca0 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 called as part
11cb0 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d of the.** implem
11cc0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 entation of an a
11cd0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
11ce0 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 ed [sqlite3_os_i
11cf0 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 nit()]..**.** Th
11d00 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
11d10 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to sqlite3_conf
11d20 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 ig() is an integ
11d30 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 er.** [configura
11d40 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 tion option] tha
11d50 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 t determines.**
11d60 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 what property of
11d70 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 SQLite is to be
11d80 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 configured. Su
11d90 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e bsequent argumen
11da0 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e ts.** vary depen
11db0 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e ding on the [con
11dc0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
11dd0 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 n].** in the fir
11de0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a st argument..**.
11df0 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 ** ^When a confi
11e00 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
11e10 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f is set, sqlite3_
11e20 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 config() returns
11e30 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a [SQLITE_OK]..**
11e40 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 ^If the option
11e50 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 is unknown or SQ
11e60 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 Lite is unable t
11e70 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e o set the option
11e80 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f .** then this ro
11e90 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 utine returns a
11ea0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 non-zero [error
11eb0 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 code]..*/.int sq
11ec0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 lite3_config(int
11ed0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , ...);../*.** C
11ee0 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
11ef0 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e re database conn
11f00 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f ections.** METHO
11f10 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
11f20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f The sqlite3_db_
11f30 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 config() interfa
11f40 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 ce is used to ma
11f50 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ke configuration
11f60 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 .** changes to a
11f70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
11f80 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 ction]. The int
11f90 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 erface is simila
11fa0 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 r to.** [sqlite3
11fb0 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 _config()] excep
11fc0 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 t that the chang
11fd0 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 es apply to a si
11fe0 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 ngle.** [databas
11ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 e connection] (s
12000 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 pecified in the
12010 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e first argument).
12020 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e .**.** The secon
12030 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 d argument to sq
12040 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
12050 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 D,V,...) is the
12060 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f .** [SQLITE_DBCO
12070 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c NFIG_LOOKASIDE |
12080 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 configuration v
12090 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 erb] - an intege
120a0 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 r code .** that
120b0 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 indicates what a
120c0 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 spect of the [da
120d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
120e0 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 n] is being conf
120f0 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 igured..** Subse
12100 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 quent arguments
12110 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f vary depending o
12120 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 n the configurat
12130 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 ion verb..**.**
12140 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 ^Calls to sqlite
12150 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 3_db_config() re
12160 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 turn SQLITE_OK i
12170 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a f and only if.**
12180 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e the call is con
12190 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 sidered successf
121a0 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ul..*/.int sqlit
121b0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c e3_db_config(sql
121c0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e ite3*, int op, .
121d0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
121e0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
121f0 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 ocation Routines
12200 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e .**.** An instan
12210 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
12220 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e t defines the in
12230 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 terface between
12240 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f SQLite.** and lo
12250 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 w-level memory a
12260 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
12270 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f es..**.** This o
12280 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e bject is used in
12290 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 only one place
122a0 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e in the SQLite in
122b0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f terface..** A po
122c0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
122d0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
122e0 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d ect is the argum
122f0 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ent to.** [sqlit
12300 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 e3_config()] whe
12310 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 n the configurat
12320 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a ion option is.**
12330 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
12340 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 MALLOC] or [SQLI
12350 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
12360 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 LOC]. .** By cr
12370 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e eating an instan
12380 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
12390 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 t.** and passing
123a0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f it to [sqlite3_
123b0 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f config]([SQLITE_
123c0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a CONFIG_MALLOC]).
123d0 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 ** during config
123e0 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c uration, an appl
123f0 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 ication can spec
12400 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 ify an alternati
12410 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c ve.** memory all
12420 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 ocation subsyste
12430 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 m for SQLite to
12440 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 use for all of i
12450 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 ts.** dynamic me
12460 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a mory needs..**.*
12470 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 * Note that SQLi
12480 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 te comes with se
12490 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 veral [built-in
124a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
124b0 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 s].** that are p
124c0 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 erfectly adequat
124d0 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 e for the overwh
124e0 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 elming majority
124f0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a of applications.
12500 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 ** and that this
12510 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 object is only
12520 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 useful to a tiny
12530 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 minority of app
12540 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 lications.** wit
12550 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 h specialized me
12560 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
12570 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 requirements. T
12580 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a his object is.**
12590 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e also used durin
125a0 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c g testing of SQL
125b0 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ite in order to
125c0 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 specify an alter
125d0 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 native.** memory
125e0 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 allocator that
125f0 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 simulates memory
12600 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 out-of-memory c
12610 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 onditions in.**
12620 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 order to verify
12630 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f that SQLite reco
12640 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 vers gracefully
12650 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e from such.** con
12660 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 ditions..**.** T
12670 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 he xMalloc, xRea
12680 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 lloc, and xFree
12690 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 methods must wor
126a0 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 k like the.** ma
126b0 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 lloc(), realloc(
126c0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e ) and free() fun
126d0 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 ctions from the
126e0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
126f0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 ry..** ^SQLite g
12700 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 uarantees that t
12710 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
12720 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f nt to.** xReallo
12730 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 c is always a va
12740 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
12750 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 a prior call to
12760 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 xRoundup..**.**
12770 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 xSize should ret
12780 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 urn the allocate
12790 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f d size of a memo
127a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ry allocation.**
127b0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 previously obta
127c0 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f ined from xMallo
127d0 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 c or xRealloc.
127e0 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 The allocated si
127f0 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 ze.** is always
12800 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 at least as big
12810 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 as the requested
12820 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 size but may be
12830 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 larger..**.** T
12840 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 he xRoundup meth
12850 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 od returns what
12860 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c would be the all
12870 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a ocated size of.*
12880 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 * a memory alloc
12890 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 ation given a pa
128a0 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 rticular request
128b0 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d ed size. Most m
128c0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
128d0 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d ors round up mem
128e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 ory allocations
128f0 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 at least to the
12900 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a next multiple.**
12910 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c of 8. Some all
12920 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 ocators round up
12930 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c to a larger mul
12940 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f tiple or to a po
12950 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 wer of 2..** Eve
12960 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ry memory alloca
12970 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d tion request com
12980 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b ing in through [
12990 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
129a0 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ].** or [sqlite3
129b0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 _realloc()] firs
129c0 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 t calls xRoundup
129d0 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 . If xRoundup r
129e0 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 eturns 0, .** th
129f0 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f at causes the co
12a00 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f rresponding memo
12a10 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f ry allocation to
12a20 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 fail..**.** The
12a30 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e xInit method in
12a40 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 itializes the me
12a50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 mory allocator.
12a60 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a For example,.**
12a70 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 it might alloca
12a80 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d te any require m
12a90 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 utexes or initia
12aa0 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 lize internal da
12ab0 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 ta.** structures
12ac0 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e . The xShutdown
12ad0 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b method is invok
12ae0 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 ed (indirectly)
12af0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 by.** [sqlite3_s
12b00 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 hutdown()] and s
12b10 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 hould deallocate
12b20 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 any resources a
12b30 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 cquired.** by xI
12b40 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 nit. The pAppDa
12b50 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 ta pointer is us
12b60 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 ed as the only p
12b70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 arameter to.** x
12b80 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f Init and xShutdo
12b90 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 wn..**.** SQLite
12ba0 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 holds the [SQLI
12bb0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
12bc0 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 MASTER] mutex wh
12bd0 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a en it invokes.**
12be0 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f the xInit metho
12bf0 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 d, so the xInit
12c00 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 method need not
12c10 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 be threadsafe.
12c20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e The.** xShutdown
12c30 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 method is only
12c40 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c called from [sql
12c50 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
12c60 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e so it does.** n
12c70 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 ot need to be th
12c80 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e readsafe either.
12c90 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 For all other
12ca0 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a methods, SQLite.
12cb0 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 ** holds the [SQ
12cc0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
12cd0 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 C_MEM] mutex as
12ce0 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b long as the.** [
12cf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
12d00 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 MSTATUS] configu
12d10 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
12d20 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 turned on (whic
12d30 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 h.** it is by de
12d40 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 fault) and so th
12d50 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 e methods are au
12d60 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 tomatically seri
12d70 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 alized..** Howev
12d80 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 er, if [SQLITE_C
12d90 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d ONFIG_MEMSTATUS]
12da0 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 is disabled, th
12db0 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 en the other.**
12dc0 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 methods must be
12dd0 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c threadsafe or el
12de0 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 se make their ow
12df0 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 n arrangements f
12e00 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 or.** serializat
12e10 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 ion..**.** SQLit
12e20 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 e will never inv
12e30 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 oke xInit() more
12e40 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f than once witho
12e50 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e ut an intervenin
12e60 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 g.** call to xSh
12e70 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 utdown()..*/.typ
12e80 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
12e90 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 te3_mem_methods
12ea0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
12eb0 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
12ec0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 te3_mem_methods
12ed0 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c {. void *(*xMal
12ee0 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 loc)(int);
12ef0 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c /* Memory all
12f00 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e ocation function
12f10 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 */. void (*xFr
12f20 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 ee)(void*);
12f30 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 /* Free a p
12f40 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
12f50 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 */. void *(*xRe
12f60 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 alloc)(void*,int
12f70 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e ); /* Resize an
12f80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
12f90 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f int (*xSize)(vo
12fa0 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 id*);
12fb0 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 /* Return the si
12fc0 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 ze of an allocat
12fd0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ion */. int (*x
12fe0 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 Roundup)(int);
12ff0 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 /* Round
13000 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 up request size
13010 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 to allocation s
13020 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ize */. int (*x
13030 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 Init)(void*);
13040 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 /* Initi
13050 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 alize the memory
13060 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 allocator */.
13070 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e void (*xShutdown
13080 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f )(void*); /
13090 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 * Deinitialize t
130a0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
130b0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 tor */. void *p
130c0 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 AppData;
130d0 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d /* Argum
130e0 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 ent to xInit() a
130f0 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a nd xShutdown() *
13100 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
13110 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 3REF: Configurat
13120 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b ion Options.** K
13130 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 EYWORDS: {config
13140 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a uration option}.
13150 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
13160 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 tants are the av
13170 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 ailable integer
13180 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
13190 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 tions that.** ca
131a0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 n be passed as t
131b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
131c0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 t to the [sqlite
131d0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 3_config()] inte
131e0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 rface..**.** New
131f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
13200 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 ptions may be ad
13210 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
13220 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
13230 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f ..** Existing co
13240 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
13250 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 ons might be dis
13260 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c continued. Appl
13270 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 ications.** shou
13280 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ld check the ret
13290 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 urn code from [s
132a0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
132b0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 to make sure th
132c0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 at.** the call w
132d0 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c orked. The [sql
132e0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 ite3_config()] i
132f0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 nterface will re
13300 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 turn a.** non-ze
13310 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ro [error code]
13320 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 if a discontinue
13330 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 d or unsupported
13340 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
13350 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f ption.** is invo
13360 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ked..**.** <dl>.
13370 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
13380 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d IG_SINGLETHREAD]
13390 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
133a0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
133b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
133c0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 re are no argume
133d0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
133e0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f on. ^This optio
133f0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 n sets the.** [t
13400 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 hreading mode] t
13410 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e o Single-thread.
13420 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 In other words
13430 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a , it disables.**
13440 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e all mutexing an
13450 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e d puts SQLite in
13460 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 to a mode where
13470 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 it can only be u
13480 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 sed.** by a sing
13490 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 le thread. ^If
134a0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
134b0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
134c0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
134d0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
134e0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
134f0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
13500 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 en.** it is not
13510 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e possible to chan
13520 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ge the [threadin
13530 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 g mode] from its
13540 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 default.** valu
13550 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 e of Single-thre
13560 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 ad and so [sqlit
13570 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c e3_config()] wil
13580 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 l return .** [SQ
13590 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 LITE_ERROR] if c
135a0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 alled with the S
135b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
135c0 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e GLETHREAD.** con
135d0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
135e0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b n.</dd>.**.** [[
135f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
13600 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e LTITHREAD]] <dt>
13610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
13620 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a LTITHREAD</dt>.*
13630 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 * <dd>There are
13640 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 no arguments to
13650 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 this option. ^T
13660 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 his option sets
13670 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e the.** [threadin
13680 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 g mode] to Multi
13690 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 -thread. In oth
136a0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 er words, it dis
136b0 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e ables.** mutexin
136c0 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 g on [database c
136d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b onnection] and [
136e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
136f0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 nt] objects..**
13700 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
13710 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
13720 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 or serializing a
13730 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 ccess to.** [dat
13740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
13750 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 s] and [prepared
13760 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 statements]. B
13770 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 ut other mutexes
13780 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 .** are enabled
13790 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 so that SQLite w
137a0 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 ill be safe to u
137b0 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 se in a multi-th
137c0 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f readed.** enviro
137d0 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 nment as long as
137e0 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 no two threads
137f0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 attempt to use t
13800 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 he same.** [data
13810 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
13820 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
13830 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 e. ^If SQLite i
13840 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
13850 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
13860 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
13870 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
13880 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
13890 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 tion then.** it
138a0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 is not possible
138b0 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 to set the Multi
138c0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 -thread [threadi
138d0 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 ng mode] and.**
138e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
138f0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b )] will return [
13900 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
13910 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 called with the
13920 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 .** SQLITE_CONFI
13930 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f G_MULTITHREAD co
13940 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
13950 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b on.</dd>.**.** [
13960 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
13970 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e ERIALIZED]] <dt>
13980 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
13990 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a RIALIZED</dt>.**
139a0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
139b0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
139c0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 his option. ^Th
139d0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
139e0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 he.** [threading
139f0 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c mode] to Serial
13a00 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 ized. In other w
13a10 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f ords, this optio
13a20 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c n enables.** all
13a30 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 mutexes includi
13a40 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 ng the recursive
13a50 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b .** mutexes on [
13a60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
13a70 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ion] and [prepar
13a80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 ed statement] ob
13a90 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 jects..** In thi
13aa0 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 s mode (which is
13ab0 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 the default whe
13ac0 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 n SQLite is comp
13ad0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 iled with.** [SQ
13ae0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
13af0 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 1]) the SQLite l
13b00 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 ibrary will itse
13b10 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 lf serialize acc
13b20 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 ess.** to [datab
13b30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
13b40 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
13b50 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 tatements] so th
13b60 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 at the.** applic
13b70 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f ation is free to
13b80 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 use the same [d
13b90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
13ba0 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 on] or the.** sa
13bb0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 me [prepared sta
13bc0 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 tement] in diffe
13bd0 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 rent threads at
13be0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a the same time..*
13bf0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 * ^If SQLite is
13c00 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
13c10 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
13c20 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
13c30 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
13c40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
13c50 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 on then.** it is
13c60 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f not possible to
13c70 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 set the Seriali
13c80 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d zed [threading m
13c90 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ode] and.** [sql
13ca0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
13cb0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ill return [SQLI
13cc0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c TE_ERROR] if cal
13cd0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
13ce0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
13cf0 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 RIALIZED configu
13d00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f ration option.</
13d10 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
13d20 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
13d30 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
13d40 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e NFIG_MALLOC</dt>
13d50 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 .** <dd> ^(The S
13d60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
13d70 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 LOC option takes
13d80 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
13d90 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 nt which is .**
13da0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
13db0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
13dc0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
13dd0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
13de0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 .** The argument
13df0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c specifies.** al
13e00 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 ternative low-le
13e10 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 vel memory alloc
13e20 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 ation routines t
13e30 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 o be used in pla
13e40 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d ce of.** the mem
13e50 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
13e60 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e outines built in
13e70 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 to SQLite.)^ ^SQ
13e80 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 Lite makes.** it
13e90 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f s own private co
13ea0 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e py of the conten
13eb0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 t of the [sqlite
13ec0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 3_mem_methods] s
13ed0 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f tructure.** befo
13ee0 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f re the [sqlite3_
13ef0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 config()] call r
13f00 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a eturns.</dd>.**.
13f10 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
13f20 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c IG_GETMALLOC]] <
13f30 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
13f40 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a _GETMALLOC</dt>.
13f50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
13f60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
13f70 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b ALLOC option tak
13f80 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
13f90 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 ment which.** is
13fa0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
13fb0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
13fc0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
13fd0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
13fe0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 ..** The [sqlite
13ff0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 3_mem_methods].*
14000 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 * structure is f
14010 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 illed with the c
14020 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
14030 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
14040 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a on routines.)^.*
14050 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 * This option ca
14060 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 n be used to ove
14070 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c rload the defaul
14080 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
14090 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ion.** routines
140a0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 with a wrapper t
140b0 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 hat simulations
140c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
140d0 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 n failure or.**
140e0 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 tracks memory us
140f0 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 age, for example
14100 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b . </dd>.**.** [[
14110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d SQLITE_CONFIG_SM
14120 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 ALL_MALLOC]] <dt
14130 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
14140 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e MALL_MALLOC</dt>
14150 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 .** <dd> ^The SQ
14160 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c LITE_CONFIG_SMAL
14170 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 L_MALLOC option
14180 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 takes single arg
14190 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65 ument of.** type
141a0 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 int, interprete
141b0 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 d as a boolean,
141c0 77 68 69 63 68 20 69 66 20 74 72 75 65 20 70 72 which if true pr
141d0 6f 76 69 64 65 73 20 61 20 68 69 6e 74 20 74 6f ovides a hint to
141e0 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68 61 74 20 .** SQLite that
141f0 69 74 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 it should avoid
14200 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c large memory all
14210 6f 63 61 74 69 6f 6e 73 20 69 66 20 70 6f 73 73 ocations if poss
14220 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 ible..** SQLite
14230 77 69 6c 6c 20 72 75 6e 20 66 61 73 74 65 72 20 will run faster
14240 69 66 20 69 74 20 69 73 20 66 72 65 65 20 74 6f if it is free to
14250 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f make large memo
14260 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a ry allocations,.
14270 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61 70 70 6c ** but some appl
14280 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 70 72 ication might pr
14290 65 66 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77 efer to run slow
142a0 65 72 20 69 6e 20 65 78 63 68 61 6e 67 65 20 66 er in exchange f
142b0 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 or.** guarantees
142c0 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72 about memory fr
142d0 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 agmentation that
142e0 20 61 72 65 20 70 6f 73 73 69 62 6c 65 20 69 66 are possible if
142f0 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 large.** alloca
14300 74 69 6f 6e 73 20 61 72 65 20 61 76 6f 69 64 65 tions are avoide
14310 64 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 d. This hint is
14320 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a normally off..*
14330 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b * </dd>.**.** [[
14340 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
14350 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 MSTATUS]] <dt>SQ
14360 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
14370 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 TATUS</dt>.** <d
14380 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 d> ^The SQLITE_C
14390 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 ONFIG_MEMSTATUS
143a0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e option takes sin
143b0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 gle argument of
143c0 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 type int,.** int
143d0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f erpreted as a bo
143e0 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 olean, which ena
143f0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 bles or disables
14400 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 the collection
14410 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c of.** memory all
14420 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 ocation statisti
14430 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 cs. ^(When memor
14440 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 y allocation sta
14450 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 tistics are.** d
14460 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c isabled, the fol
14470 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e lowing SQLite in
14480 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 terfaces become
14490 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a non-operational:
144a0 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 .** <ul>.**
144b0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 <li> [sqlite3_me
144c0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 mory_used()].**
144d0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
144e0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
144f0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
14500 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 qlite3_soft_heap
14510 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 _limit64()].**
14520 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 <li> [sqlite3_s
14530 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 tatus64()].**
14540 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f </ul>)^.** ^Memo
14550 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 ry allocation st
14560 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 atistics are ena
14570 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 bled by default
14580 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 unless SQLite is
14590 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 .** compiled wit
145a0 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c h [SQLITE_DEFAUL
145b0 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 T_MEMSTATUS]=0 i
145c0 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d n which case mem
145d0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f ory.** allocatio
145e0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 n statistics are
145f0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
14600 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a ault..** </dd>.*
14610 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
14620 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c NFIG_SCRATCH]] <
14630 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
14640 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a _SCRATCH</dt>.**
14650 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 <dd> The SQLITE
14660 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 _CONFIG_SCRATCH
14670 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e option is no lon
14680 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 ger used..** </d
14690 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
146a0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
146b0 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f HE]] <dt>SQLITE_
146c0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
146d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
146e0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
146f0 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f _PAGECACHE optio
14700 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 n specifies a me
14710 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 mory pool.** tha
14720 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 t SQLite can use
14730 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 for the databas
14740 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 e page cache wit
14750 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 h the default pa
14760 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c ge.** cache impl
14770 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a ementation. .**
14780 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 This configurat
14790 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 ion option is a
147a0 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c no-op if an appl
147b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 ication-define p
147c0 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 age.** cache imp
147d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c lementation is l
147e0 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 oaded using the
147f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
14800 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 CACHE2]..** ^The
14810 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
14820 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 uments to SQLITE
14830 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
14840 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a E: A pointer to.
14850 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 ** 8-byte aligne
14860 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c d memory (pMem),
14870 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 the size of eac
14880 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e h page cache lin
14890 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 e (sz),.** and t
148a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 he number of cac
148b0 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a he lines (N)..**
148c0 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 The sz argument
148d0 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 should be the s
148e0 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 ize of the large
148f0 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 st database page
14900 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 .** (a power of
14910 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 two between 512
14920 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 and 65536) plus
14930 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 some extra bytes
14940 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 for each.** pag
14950 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 e header. ^The
14960 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 number of extra
14970 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 bytes needed by
14980 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a the page header.
14990 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d ** can be determ
149a0 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 ined using [SQLI
149b0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
149c0 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 _HDRSZ]..** ^It
149d0 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 is harmless, apa
149e0 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 rt from the wast
149f0 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f ed memory,.** fo
14a00 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 r the sz paramet
14a10 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 er to be larger
14a20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 than necessary.
14a30 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 The pMem.** arg
14a40 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 ument must be ei
14a50 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e ther a NULL poin
14a60 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 ter or a pointer
14a70 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a to an 8-byte.**
14a80 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f aligned block o
14a90 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c f memory of at l
14aa0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c east sz*N bytes,
14ab0 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 otherwise.** su
14ac0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f bsequent behavio
14ad0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a r is undefined..
14ae0 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 ** ^When pMem is
14af0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 not NULL, SQLit
14b00 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f e will strive to
14b10 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 use the memory
14b20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 provided.** to s
14b30 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68 atisfy page cach
14b40 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 e needs, falling
14b50 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 back to [sqlite
14b60 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 3_malloc()] if.*
14b70 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c * a page cache l
14b80 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 ine is larger th
14b90 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 an sz bytes or i
14ba0 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 f all of the pMe
14bb0 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 m buffer.** is e
14bc0 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 xhausted..** ^If
14bd0 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e pMem is NULL an
14be0 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c d N is non-zero,
14bf0 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 then each datab
14c00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
14c10 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 * does an initia
14c20 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f l bulk allocatio
14c30 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 n for page cache
14c40 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 memory.** from
14c50 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
14c60 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f )] sufficient fo
14c70 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 r N cache lines
14c80 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 if N is positive
14c90 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a or.** of -1024*
14ca0 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 N bytes if N is
14cb0 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 negative, . ^If
14cc0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 additional.** pa
14cd0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 ge cache memory
14ce0 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 is needed beyond
14cf0 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 what is provide
14d00 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c d by the initial
14d10 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 .** allocation,
14d20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 then SQLite goes
14d30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c to [sqlite3_mal
14d40 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c loc()] separatel
14d50 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 y for each.** ad
14d60 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c ditional cache l
14d70 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ine. </dd>.**.**
14d80 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
14d90 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 _HEAP]] <dt>SQLI
14da0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f TE_CONFIG_HEAP</
14db0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 dt>.** <dd> ^The
14dc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 SQLITE_CONFIG_H
14dd0 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 EAP option speci
14de0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
14df0 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 mory buffer .**
14e00 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c that SQLite will
14e10 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 use for all of
14e20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f its dynamic memo
14e30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
14e40 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 eds.** beyond th
14e50 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 ose provided for
14e60 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 by [SQLITE_CONF
14e70 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a IG_PAGECACHE]..*
14e80 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f * ^The SQLITE_CO
14e90 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e NFIG_HEAP option
14ea0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 is only availab
14eb0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 le if SQLite is
14ec0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 compiled.** with
14ed0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f either [SQLITE_
14ee0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 ENABLE_MEMSYS3]
14ef0 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c or [SQLITE_ENABL
14f00 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 E_MEMSYS5] and r
14f10 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 eturns.** [SQLIT
14f20 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f E_ERROR] if invo
14f30 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a ked otherwise..*
14f40 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 * ^There are thr
14f50 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 ee arguments to
14f60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 SQLITE_CONFIG_HE
14f70 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 AP:.** An 8-byte
14f80 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 aligned pointer
14f90 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a to the memory,.
14fa0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
14fb0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 bytes in the me
14fc0 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 mory buffer, and
14fd0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c the minimum all
14fe0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a ocation size..**
14ff0 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 ^If the first p
15000 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f ointer (the memo
15010 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e ry pointer) is N
15020 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ULL, then SQLite
15030 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 reverts.** to u
15040 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 sing its default
15050 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
15060 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 r (the system ma
15070 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 lloc() implement
15080 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 ation),.** undoi
15090 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 ng any prior inv
150a0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 ocation of [SQLI
150b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
150c0 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d ]. ^If the.** m
150d0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 emory pointer is
150e0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 not NULL then t
150f0 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d he alternative m
15100 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
15110 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f or is engaged to
15120 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 handle all of S
15130 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c QLites memory al
15140 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a location needs..
15150 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 ** The first poi
15160 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 nter (the memory
15170 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 pointer) must b
15180 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
15190 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 8-byte.** bounda
151a0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 ry or subsequent
151b0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c behavior of SQL
151c0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 ite will be unde
151d0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 fined..** The mi
151e0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
151f0 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 size is capped
15200 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e at 2**12. Reason
15210 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 able values.** f
15220 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 or the minimum a
15230 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 llocation size a
15240 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 re 2**5 through
15250 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 2**8.</dd>.**.**
15260 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
15270 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c _MUTEX]] <dt>SQL
15280 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
15290 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
152a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
152b0 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 G_MUTEX option t
152c0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
152d0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
152e0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 a.** pointer to
152f0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
15300 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
15310 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 x_methods] struc
15320 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 ture..** The arg
15330 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 ument specifies
15340 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d alternative low-
15350 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 level mutex rout
15360 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a ines to be used.
15370 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 ** in place the
15380 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 mutex routines b
15390 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 uilt into SQLite
153a0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b .)^ ^SQLite mak
153b0 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 es a copy of.**
153c0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
153d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
153e0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 x_methods] struc
153f0 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 ture before the
15400 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
15410 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 te3_config()] re
15420 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 turns. ^If SQLit
15430 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
15440 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 th.** the [SQLIT
15450 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 E_THREADSAFE | S
15460 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
15470 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =0] compile-time
15480 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 option then.**
15490 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 the entire mutex
154a0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 ing subsystem is
154b0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 omitted from th
154c0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 e build and henc
154d0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 e calls to.** [s
154e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
154f0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 with the SQLITE
15500 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f _CONFIG_MUTEX co
15510 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
15520 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 on will.** retur
15530 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d n [SQLITE_ERROR]
15540 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
15550 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
15560 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 MUTEX]] <dt>SQLI
15570 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
15580 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 EX</dt>.** <dd>
15590 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^(The SQLITE_CON
155a0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 FIG_GETMUTEX opt
155b0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
155c0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
155d0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 h.** is a pointe
155e0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 r to an instance
155f0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
15600 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 _mutex_methods]
15610 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a structure. The.
15620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 ** [sqlite3_mute
15630 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 x_methods].** st
15640 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 ructure is fille
15650 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 d with the curre
15660 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 ntly defined mut
15670 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a ex routines.)^.*
15680 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 * This option ca
15690 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 n be used to ove
156a0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c rload the defaul
156b0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 t mutex allocati
156c0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 on.** routines w
156d0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 ith a wrapper us
156e0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 ed to track mute
156f0 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 x usage for perf
15700 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 ormance.** profi
15710 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c ling or testing,
15720 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 for example.
15730 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
15740 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
15750 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
15760 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
15770 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
15780 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
15790 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 then.** the ent
157a0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 ire mutexing sub
157b0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 system is omitte
157c0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 d from the build
157d0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 and hence calls
157e0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
157f0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 config()] with t
15800 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
15810 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 _GETMUTEX config
15820 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 uration option w
15830 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 ill.** return [S
15840 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 QLITE_ERROR].</d
15850 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
15860 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
15870 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f DE]] <dt>SQLITE_
15880 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
15890 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
158a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
158b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 G_LOOKASIDE opti
158c0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 on takes two arg
158d0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 uments that dete
158e0 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 rmine.** the def
158f0 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f ault size of loo
15900 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e kaside memory on
15910 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 each [database
15920 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 connection]..**
15930 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
15940 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a nt is the.** siz
15950 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 e of each lookas
15960 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 ide buffer slot
15970 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 and the second i
15980 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a s the number of.
15990 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 ** slots allocat
159a0 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 ed to each datab
159b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 ase connection.)
159c0 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 ^ ^(SQLITE_CONF
159d0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 IG_LOOKASIDE.**
159e0 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 sets the <i>defa
159f0 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 ult</i> lookasid
15a00 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c e size. The [SQL
15a10 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
15a20 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f KASIDE].** optio
15a30 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 n to [sqlite3_db
15a40 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 _config()] can b
15a50 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 e used to change
15a60 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a the lookaside.*
15a70 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 * configuration
15a80 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f on individual co
15a90 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 nnections.)^ </d
15aa0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
15ab0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 E_CONFIG_PCACHE2
15ac0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
15ad0 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 NFIG_PCACHE2</dt
15ae0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 >.** <dd> ^(The
15af0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
15b00 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b ACHE2 option tak
15b10 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
15b20 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a ment which is .*
15b30 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * a pointer to a
15b40 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 n [sqlite3_pcach
15b50 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 e_methods2] obje
15b60 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 ct. This object
15b70 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 specifies.** th
15b80 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 e interface to a
15b90 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 custom page cac
15ba0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
15bb0 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 n.)^.** ^SQLite
15bc0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
15bd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 the [sqlite3_pca
15be0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 che_methods2] ob
15bf0 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ject.</dd>.**.**
15c00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
15c10 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 _GETPCACHE2]] <d
15c20 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
15c30 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a GETPCACHE2</dt>.
15c40 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
15c50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
15c60 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 CACHE2 option ta
15c70 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
15c80 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 ument which.** i
15c90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
15ca0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 n [sqlite3_pcach
15cb0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 e_methods2] obje
15cc0 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 ct. SQLite copi
15cd0 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 es of.** the cur
15ce0 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 rent page cache
15cf0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
15d00 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e nto that object.
15d10 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b )^ </dd>.**.** [
15d20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c [SQLITE_CONFIG_L
15d30 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f OG]] <dt>SQLITE_
15d40 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a CONFIG_LOG</dt>.
15d50 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 ** <dd> The SQLI
15d60 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 TE_CONFIG_LOG op
15d70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
15d80 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 configure the SQ
15d90 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b Lite.** global [
15da0 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 error log]..** (
15db0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
15dc0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 IG_LOG option ta
15dd0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 kes two argument
15de0 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 s: a pointer to
15df0 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 a.** function wi
15e00 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 th a call signat
15e10 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 ure of void(*)(v
15e20 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 oid*,int,const c
15e30 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 har*), .** and a
15e40 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 pointer to void
15e50 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 . ^If the functi
15e60 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f on pointer is no
15e70 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a t NULL, it is.**
15e80 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c invoked by [sql
15e90 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 ite3_log()] to p
15ea0 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 rocess each logg
15eb0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 ing event. ^If
15ec0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 the.** function
15ed0 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c pointer is NULL,
15ee0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f the [sqlite3_lo
15ef0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 g()] interface b
15f00 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a ecomes a no-op..
15f10 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 ** ^The void poi
15f20 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 nter that is the
15f30 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
15f40 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 to SQLITE_CONFI
15f50 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 G_LOG is.** pass
15f60 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 ed through as th
15f70 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
15f80 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 r to the applica
15f90 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 tion-defined log
15fa0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ger.** function
15fb0 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 whenever that fu
15fc0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 nction is invoke
15fd0 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 d. ^The second
15fe0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
15ff0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 the logger funct
16000 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ion is a copy of
16010 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
16020 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 eter to the corr
16030 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 esponding.** [sq
16040 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c lite3_log()] cal
16050 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 l and is intende
16060 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c d to be a [resul
16070 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a t code] or an.**
16080 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
16090 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 t code]. ^The t
160a0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 hird parameter p
160b0 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 assed to the log
160c0 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 ger is.** log me
160d0 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d ssage after form
160e0 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 atting via [sqli
160f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e te3_snprintf()].
16100 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c .** The SQLite l
16110 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 ogging interface
16120 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e is not reentran
16130 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 t; the logger fu
16140 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 nction.** suppli
16150 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ed by the applic
16160 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 ation must not i
16170 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 nvoke any SQLite
16180 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 interface..** I
16190 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 n a multi-thread
161a0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 ed application,
161b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
161c0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a defined logger.*
161d0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 * function must
161e0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c be threadsafe. <
161f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
16200 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d ITE_CONFIG_URI]]
16210 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
16220 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 IG_URI.** <dd>^(
16230 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
16240 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b G_URI option tak
16250 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
16260 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 ment of type int
16270 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f ..** If non-zero
16280 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c , then URI handl
16290 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 ing is globally
162a0 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 enabled. If the
162b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 parameter is zer
162c0 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 o,.** then URI h
162d0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 andling is globa
162e0 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 lly disabled.)^
162f0 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 ^If URI handling
16300 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 is globally.**
16310 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c enabled, all fil
16320 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f enames passed to
16330 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
16340 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
16350 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 _v2()],.** [sqli
16360 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 te3_open16()] or
16370 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 .** specified as
16380 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 part of [ATTACH
16390 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 ] commands are i
163a0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 nterpreted as UR
163b0 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a Is, regardless.*
163c0 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 * of whether or
163d0 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f not the [SQLITE_
163e0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 OPEN_URI] flag i
163f0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 s set when the d
16400 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
16410 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e ction is opened.
16420 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 ^If it is globa
16430 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 lly disabled, fi
16440 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f lenames are.** o
16450 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 nly interpreted
16460 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 as URIs if the S
16470 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 QLITE_OPEN_URI f
16480 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 lag is set when
16490 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
164a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 connection is op
164b0 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 ened. ^(By defau
164c0 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 lt, URI handling
164d0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 is globally.**
164e0 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 disabled. The de
164f0 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 fault value may
16500 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f be changed by co
16510 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 mpiling with the
16520 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f .** [SQLITE_USE_
16530 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 URI] symbol defi
16540 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 ned.)^.**.** [[S
16550 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 QLITE_CONFIG_COV
16560 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e ERING_INDEX_SCAN
16570 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
16580 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e NFIG_COVERING_IN
16590 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e DEX_SCAN.** <dd>
165a0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
165b0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 IG_COVERING_INDE
165c0 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 X_SCAN option ta
165d0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 kes a single int
165e0 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 eger.** argument
165f0 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 which is interp
16600 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 reted as a boole
16610 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 an in order to e
16620 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 nable or disable
16630 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 .** the use of c
16640 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 overing indices
16650 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 for full table s
16660 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 cans in the quer
16670 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 y optimizer..**
16680 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 ^The default set
16690 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e ting is determin
166a0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 ed.** by the [SQ
166b0 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 LITE_ALLOW_COVER
166c0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 ING_INDEX_SCAN]
166d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
166e0 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a ion, or is "on".
166f0 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 ** if that compi
16700 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 le-time option i
16710 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 s omitted..** Th
16720 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 e ability to dis
16730 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 able the use of
16740 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 covering indices
16750 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 for full table
16760 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 scans.** is beca
16770 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 use some incorre
16780 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 ctly coded legac
16790 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d y applications m
167a0 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e ight malfunction
167b0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 .** when the opt
167c0 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 imization is ena
167d0 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 bled. Providing
167e0 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a the ability to.
167f0 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f ** disable the o
16800 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f ptimization allo
16810 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 ws the older, bu
16820 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 ggy application
16830 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 code to work.**
16840 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 without change e
16850 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 ven with newer v
16860 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
16870 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 e..**.** [[SQLIT
16880 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d E_CONFIG_PCACHE]
16890 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ] [[SQLITE_CONFI
168a0 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a G_GETPCACHE]].**
168b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
168c0 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 IG_PCACHE and SQ
168d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
168e0 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 CACHE.** <dd> Th
168f0 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 ese options are
16900 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f obsolete and sho
16910 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 uld not be used
16920 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 by new code..**
16930 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 They are retaine
16940 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 d for backwards
16950 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 compatibility bu
16960 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 t are now no-ops
16970 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ..** </dd>.**.**
16980 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
16990 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 _SQLLOG]].** <dt
169a0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
169b0 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 QLLOG.** <dd>Thi
169c0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 s option is only
169d0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 available if sq
169e0 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 lite is compiled
169f0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 with the.** [SQ
16a00 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c LITE_ENABLE_SQLL
16a10 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f OG] pre-processo
16a20 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e r macro defined.
16a30 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
16a40 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 ent should.** be
16a50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
16a60 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 function of type
16a70 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 void(*)(void*,s
16a80 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 qlite3*,const ch
16a90 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 ar*, int)..** Th
16aa0 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 e second should
16ab0 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 be of type (void
16ac0 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b *). The callback
16ad0 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 is invoked by t
16ae0 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e he library.** in
16af0 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 three separate
16b00 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 circumstances, i
16b10 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 dentified by the
16b20 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 value passed as
16b30 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 the.** fourth p
16b40 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 arameter. If the
16b50 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
16b60 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 r is 0, then the
16b70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
16b80 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 tion.** passed a
16b90 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
16ba0 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 ument has just b
16bb0 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 een opened. The
16bc0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a third argument.*
16bd0 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 * points to a bu
16be0 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 ffer containing
16bf0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
16c00 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 main database fi
16c10 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f le. If the.** fo
16c20 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
16c30 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 s 1, then the SQ
16c40 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 L statement that
16c50 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
16c60 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 eter.** points t
16c70 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 o has just been
16c80 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 executed. Or, if
16c90 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
16ca0 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e meter is 2, then
16cb0 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 .** the connecti
16cc0 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 on being passed
16cd0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
16ce0 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 rameter is being
16cf0 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 closed. The.**
16d00 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
16d10 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 is passed NULL I
16d20 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e n this case. An
16d30 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e example of usin
16d40 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 g this.** config
16d50 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 uration option c
16d60 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 an be seen in th
16d70 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 e "test_sqllog.c
16d80 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e " source file in
16d90 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 .** the canonica
16da0 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 l SQLite source
16db0 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tree.</dd>.**.**
16dc0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
16dd0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 _MMAP_SIZE]].**
16de0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
16df0 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c G_MMAP_SIZE.** <
16e00 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 dd>^SQLITE_CONFI
16e10 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 G_MMAP_SIZE take
16e20 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 s two 64-bit int
16e30 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e eger (sqlite3_in
16e40 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 t64) values.** t
16e50 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 hat are the defa
16e60 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 ult mmap size li
16e70 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 mit (the default
16e80 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 setting for.**
16e90 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a [PRAGMA mmap_siz
16ea0 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 e]) and the maxi
16eb0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 mum allowed mmap
16ec0 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 size limit..**
16ed0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 ^The default set
16ee0 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 ting can be over
16ef0 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 ridden by each d
16f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
16f10 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 on using.** eith
16f20 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d er the [PRAGMA m
16f30 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e map_size] comman
16f40 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 d, or by using t
16f50 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 he.** [SQLITE_FC
16f60 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 NTL_MMAP_SIZE] f
16f70 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 ile control. ^(
16f80 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f The maximum allo
16f90 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a wed mmap size.**
16fa0 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c will be silentl
16fb0 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e y truncated if n
16fc0 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 ecessary so that
16fd0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 it does not exc
16fe0 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 eed the.** compi
16ff0 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 le-time maximum
17000 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 mmap size set by
17010 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
17020 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 MAX_MMAP_SIZE] c
17030 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
17040 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 on.)^.** ^If eit
17050 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 her argument to
17060 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e this option is n
17070 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 egative, then th
17080 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a at argument is.*
17090 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 * changed to its
170a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 compile-time de
170b0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 fault..**.** [[S
170c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e QLITE_CONFIG_WIN
170d0 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 32_HEAPSIZE]].**
170e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
170f0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a IG_WIN32_HEAPSIZ
17100 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 E.** <dd>^The SQ
17110 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 LITE_CONFIG_WIN3
17120 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 2_HEAPSIZE optio
17130 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 n is only availa
17140 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 ble if SQLite is
17150 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 .** compiled for
17160 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 Windows with th
17170 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f e [SQLITE_WIN32_
17180 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 MALLOC] pre-proc
17190 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 essor macro.** d
171a0 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f efined. ^SQLITE_
171b0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 CONFIG_WIN32_HEA
171c0 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 PSIZE takes a 32
171d0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e -bit unsigned in
171e0 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 teger value.** t
171f0 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 hat specifies th
17200 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f e maximum size o
17210 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 f the created he
17220 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 ap..**.** [[SQLI
17230 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
17240 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e _HDRSZ]].** <dt>
17250 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
17260 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 ACHE_HDRSZ.** <d
17270 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f d>^The SQLITE_CO
17280 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 NFIG_PCACHE_HDRS
17290 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 Z option takes a
172a0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 single paramete
172b0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 r which.** is a
172c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
172d0 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 teger and writes
172e0 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 into that integ
172f0 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 er the number of
17300 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 extra.** bytes
17310 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 per page require
17320 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 d for each page
17330 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 in [SQLITE_CONFI
17340 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a G_PAGECACHE]..**
17350 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 The amount of e
17360 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 xtra space requi
17370 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 red can change d
17380 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
17390 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 compiler,.** tar
173a0 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e get platform, an
173b0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e d SQLite version
173c0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ..**.** [[SQLITE
173d0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a _CONFIG_PMASZ]].
173e0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
173f0 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 NFIG_PMASZ.** <d
17400 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f d>^The SQLITE_CO
17410 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f NFIG_PMASZ optio
17420 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
17430 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 parameter which
17440 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e .** is an unsign
17450 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 ed integer and s
17460 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d ets the "Minimum
17470 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 PMA Size" for t
17480 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 he multithreaded
17490 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 .** sorter to th
174a0 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 at integer. The
174b0 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d default minimum
174c0 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 PMA Size is set
174d0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 by the.** [SQLI
174e0 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d TE_SORTER_PMASZ]
174f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
17500 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 tion. New threa
17510 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a ds are launched.
17520 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 ** to help with
17530 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 sort operations
17540 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 when multithread
17550 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 ed sorting.** is
17560 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 enabled (using
17570 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 the [PRAGMA thre
17580 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e ads] command) an
17590 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 d the amount of
175a0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 content.** to be
175b0 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 sorted exceeds
175c0 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 the page size ti
175d0 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 mes the minimum
175e0 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d of the.** [PRAGM
175f0 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 A cache_size] se
17600 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 tting and this v
17610 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 alue..**.** [[SQ
17620 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 LITE_CONFIG_STMT
17630 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 JRNL_SPILL]].**
17640 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
17650 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c G_STMTJRNL_SPILL
17660 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c .** <dd>^The SQL
17670 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a ITE_CONFIG_STMTJ
17680 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e RNL_SPILL option
17690 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
176a0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a parameter which.
176b0 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b ** becomes the [
176c0 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 statement journa
176d0 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b l] spill-to-disk
176e0 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a threshold. .**
176f0 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 [Statement jour
17700 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69 nals] are held i
17710 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 n memory until t
17720 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79 heir size (in by
17730 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 tes).** exceeds
17740 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 this threshold,
17750 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74 at which point t
17760 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20 hey are written
17770 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 to disk..** Or i
17780 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20 f the threshold
17790 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 is -1, statement
177a0 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c journals are al
177b0 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 ways held.** exc
177c0 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f lusively in memo
177d0 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e ry..** Since man
177e0 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 y statement jour
177f0 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d nals never becom
17800 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67 e large, setting
17810 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 the spill.** th
17820 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c reshold to a val
17830 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42 ue such as 64KiB
17840 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64 can greatly red
17850 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f uce the amount o
17860 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 f.** I/O require
17870 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61 d to support sta
17880 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e tement rollback.
17890 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 .** The default
178a0 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73 value for this s
178b0 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f etting is contro
178c0 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b lled by the.** [
178d0 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f SQLITE_STMTJRNL_
178e0 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 SPILL] compile-t
178f0 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a ime option..**.*
17900 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
17910 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 G_SORTERREF_SIZE
17920 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
17930 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 _CONFIG_SORTERRE
17940 46 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68 F_SIZE.** <dd>Th
17950 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
17960 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 20 6f SORTERREF_SIZE o
17970 70 74 69 6f 6e 20 61 63 63 65 70 74 73 20 61 20 ption accepts a
17980 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 single parameter
17990 0a 2a 2a 20 6f 66 20 74 79 70 65 20 28 69 6e 74 .** of type (int
179a0 29 20 2d 20 74 68 65 20 6e 65 77 20 76 61 6c 75 ) - the new valu
179b0 65 20 6f 66 20 74 68 65 20 73 6f 72 74 65 72 2d e of the sorter-
179c0 72 65 66 65 72 65 6e 63 65 20 73 69 7a 65 20 74 reference size t
179d0 68 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55 73 75 hreshold..** Usu
179e0 61 6c 6c 79 2c 20 77 68 65 6e 20 53 51 4c 69 74 ally, when SQLit
179f0 65 20 75 73 65 73 20 61 6e 20 65 78 74 65 72 6e e uses an extern
17a00 61 6c 20 73 6f 72 74 20 74 6f 20 6f 72 64 65 72 al sort to order
17a10 20 72 65 63 6f 72 64 73 20 61 63 63 6f 72 64 69 records accordi
17a20 6e 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52 44 45 ng.** to an ORDE
17a30 52 20 42 59 20 63 6c 61 75 73 65 2c 20 61 6c 6c R BY clause, all
17a40 20 66 69 65 6c 64 73 20 72 65 71 75 69 72 65 64 fields required
17a50 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 20 61 by the caller a
17a60 72 65 20 70 72 65 73 65 6e 74 20 69 6e 20 74 68 re present in th
17a70 65 0a 2a 2a 20 73 6f 72 74 65 64 20 72 65 63 6f e.** sorted reco
17a80 72 64 73 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 rds. However, if
17a90 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e SQLite determin
17aa0 65 73 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20 es based on the
17ab0 64 65 63 6c 61 72 65 64 20 74 79 70 65 0a 2a 2a declared type.**
17ac0 20 6f 66 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 of a table colu
17ad0 6d 6e 20 74 68 61 74 20 69 74 73 20 76 61 6c 75 mn that its valu
17ae0 65 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f es are likely to
17af0 20 62 65 20 76 65 72 79 20 6c 61 72 67 65 20 2d be very large -
17b00 20 6c 61 72 67 65 72 0a 2a 2a 20 74 68 61 6e 20 larger.** than
17b10 74 68 65 20 63 6f 6e 66 69 67 75 72 65 64 20 73 the configured s
17b20 6f 72 74 65 72 2d 72 65 66 65 72 65 6e 63 65 20 orter-reference
17b30 73 69 7a 65 20 74 68 72 65 73 68 6f 6c 64 20 2d size threshold -
17b40 20 74 68 65 6e 20 61 20 72 65 66 65 72 65 6e 63 then a referenc
17b50 65 0a 2a 2a 20 69 73 20 73 74 6f 72 65 64 20 69 e.** is stored i
17b60 6e 20 65 61 63 68 20 73 6f 72 74 65 64 20 72 65 n each sorted re
17b70 63 6f 72 64 20 61 6e 64 20 74 68 65 20 72 65 71 cord and the req
17b80 75 69 72 65 64 20 63 6f 6c 75 6d 6e 20 76 61 6c uired column val
17b90 75 65 73 20 6c 6f 61 64 65 64 0a 2a 2a 20 66 72 ues loaded.** fr
17ba0 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20 om the database
17bb0 61 73 20 72 65 63 6f 72 64 73 20 61 72 65 20 72 as records are r
17bc0 65 74 75 72 6e 65 64 20 69 6e 20 73 6f 72 74 65 eturned in sorte
17bd0 64 20 6f 72 64 65 72 2e 20 54 68 65 20 64 65 66 d order. The def
17be0 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 66 6f ault.** value fo
17bf0 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 r this option is
17c00 20 74 6f 20 6e 65 76 65 72 20 75 73 65 20 74 68 to never use th
17c10 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e is optimization.
17c20 20 53 70 65 63 69 66 79 69 6e 67 20 61 20 0a 2a Specifying a .*
17c30 2a 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 * negative value
17c40 20 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e for this option
17c50 20 72 65 73 74 6f 72 65 73 20 74 68 65 20 64 65 restores the de
17c60 66 61 75 6c 74 20 62 65 68 61 76 69 6f 75 72 2e fault behaviour.
17c70 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 .** This option
17c80 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c is only availabl
17c90 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 e if SQLite is c
17ca0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
17cb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 .** [SQLITE_ENAB
17cc0 4c 45 5f 53 4f 52 54 45 52 5f 52 45 46 45 52 45 LE_SORTER_REFERE
17cd0 4e 43 45 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 NCES] compile-ti
17ce0 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f me option..** </
17cf0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
17d00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
17d10 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a GLETHREAD 1 /*
17d20 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nil */.#define
17d30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
17d40 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f LTITHREAD 2 /
17d50 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 * nil */.#define
17d60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
17d70 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 ERIALIZED 3
17d80 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
17d90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
17da0 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 MALLOC 4
17db0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f /* sqlite3_mem_
17dc0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
17dd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
17de0 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 G_GETMALLOC
17df0 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 5 /* sqlite3_me
17e00 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 m_methods* */.#d
17e10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
17e20 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 FIG_SCRATCH
17e30 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 6 /* No longe
17e40 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e r used */.#defin
17e50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
17e60 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 PAGECACHE 7
17e70 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 /* void*, int s
17e80 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 z, int N */.#def
17e90 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
17ea0 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 G_HEAP
17eb0 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 8 /* void*, int
17ec0 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 nByte, int min
17ed0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17ee0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
17ef0 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f US 9 /* boo
17f00 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 lean */.#define
17f10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
17f20 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f TEX 10 /
17f30 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f * sqlite3_mutex_
17f40 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
17f50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
17f60 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 G_GETMUTEX 1
17f70 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 1 /* sqlite3_mu
17f80 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a tex_methods* */.
17f90 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 /* previously SQ
17fa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e LITE_CONFIG_CHUN
17fb0 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 KALLOC 12 which
17fc0 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a is now unused. *
17fd0 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 / .#define SQLIT
17fe0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
17ff0 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 DE 13 /* int
18000 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
18010 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
18020 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f ACHE 14 /
18030 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 * no-op */.#defi
18040 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18050 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 _GETPCACHE 15
18060 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 /* no-op */.#d
18070 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
18080 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 FIG_LOG
18090 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 16 /* xFunc, v
180a0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 oid* */.#define
180b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
180c0 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f I 17 /
180d0 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 * int */.#define
180e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
180f0 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 CACHE2 18
18100 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 /* sqlite3_pcach
18110 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 e_methods2* */.#
18120 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
18130 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 NFIG_GETPCACHE2
18140 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 19 /* sqlite3
18150 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 _pcache_methods2
18160 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
18170 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 ITE_CONFIG_COVER
18180 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 ING_INDEX_SCAN 2
18190 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 0 /* int */.#de
181a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
181b0 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 IG_SQLLOG
181c0 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 21 /* xSqllog,
181d0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 void* */.#define
181e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
181f0 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 MAP_SIZE 22
18200 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 /* sqlite3_int64
18210 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
18220 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18230 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 E_CONFIG_WIN32_H
18240 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 EAPSIZE 23
18250 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f /* int nByte */
18260 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18270 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 CONFIG_PCACHE_HD
18280 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f RSZ 24 /
18290 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 * int *psz */.#d
182a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
182b0 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 FIG_PMASZ
182c0 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 25 /* u
182d0 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d nsigned int szPm
182e0 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c a */.#define SQL
182f0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a ITE_CONFIG_STMTJ
18300 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 RNL_SPILL 2
18310 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 6 /* int nByte
18320 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18330 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d E_CONFIG_SMALL_M
18340 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20 ALLOC 27
18350 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 /* boolean */.#
18360 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
18370 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 NFIG_SORTERREF_S
18380 49 5a 45 20 20 20 20 20 20 32 38 20 20 2f 2a 20 IZE 28 /*
18390 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a int nByte */../*
183a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 .** CAPI3REF: Da
183b0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
183c0 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 n Configuration
183d0 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 Options.**.** Th
183e0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
183f0 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 e the available
18400 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 integer configur
18410 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 ation options th
18420 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 at.** can be pas
18430 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
18440 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 d argument to th
18450 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f e [sqlite3_db_co
18460 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
18470 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e e..**.** New con
18480 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
18490 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ns may be added
184a0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
184b0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
184c0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 Existing config
184d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
184e0 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 might be discont
184f0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 inued. Applicat
18500 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 ions.** should c
18510 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 heck the return
18520 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 code from [sqlit
18530 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
18540 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 to make sure tha
18550 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f t.** the call wo
18560 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c rked. ^The [sql
18570 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
18580 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c ] interface will
18590 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e return a.** non
185a0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 -zero [error cod
185b0 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 e] if a disconti
185c0 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 nued or unsuppor
185d0 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ted configuratio
185e0 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 n option.** is i
185f0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 nvoked..**.** <d
18600 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 l>.** <dt>SQLITE
18610 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
18620 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e IDE</dt>.** <dd>
18630 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 ^This option ta
18640 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 kes three additi
18650 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 onal arguments t
18660 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 hat determine th
18670 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 e .** [lookaside
18680 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
18690 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e r] configuration
186a0 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 for the [databa
186b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a se connection]..
186c0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
186d0 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 gument (the thir
186e0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b d parameter to [
186f0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
18700 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 g()] is a.** poi
18710 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 nter to a memory
18720 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 buffer to use f
18730 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d or lookaside mem
18740 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ory..** ^The fir
18750 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 st argument afte
18760 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 r the SQLITE_DBC
18770 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
18780 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e verb.** may be N
18790 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 ULL in which cas
187a0 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c e SQLite will al
187b0 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f locate the.** lo
187c0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 okaside buffer i
187d0 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c tself using [sql
187e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 ite3_malloc()].
187f0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 ^The second argu
18800 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 ment is the.** s
18810 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b ize of each look
18820 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f aside buffer slo
18830 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 t. ^The third a
18840 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e rgument is the n
18850 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 umber of.** slot
18860 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 s. The size of
18870 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 the buffer in th
18880 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
18890 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 must be greater
188a0 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 than.** or equa
188b0 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 l to the product
188c0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 of the second a
188d0 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e nd third argumen
188e0 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a ts. The buffer.
188f0 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e ** must be align
18900 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 ed to an 8-byte
18910 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 boundary. ^If t
18920 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
18930 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f nt to.** SQLITE_
18940 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
18950 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 DE is not a mult
18960 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 iple of 8, it is
18970 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 internally.** r
18980 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 ounded down to t
18990 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 he next smaller
189a0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 multiple of 8.
189b0 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 ^(The lookaside
189c0 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 memory.** config
189d0 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 uration for a da
189e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
189f0 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 n can only be ch
18a00 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a anged when that.
18a10 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 ** connection is
18a20 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 not currently u
18a30 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d sing lookaside m
18a40 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 emory, or in oth
18a50 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e er words.** when
18a60 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 the "current va
18a70 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 lue" returned by
18a80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f .** [sqlite3_db_
18a90 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 status](D,[SQLIT
18aa0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
18ab0 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f DE],...) is zero
18ac0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 ..** Any attempt
18ad0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c to change the l
18ae0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
18af0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 configuration wh
18b00 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 en lookaside.**
18b10 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 memory is in use
18b20 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 leaves the conf
18b30 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e iguration unchan
18b40 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ged and returns
18b50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 .** [SQLITE_BUSY
18b60 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ].)^</dd>.**.**
18b70 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e <dt>SQLITE_DBCON
18b80 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c FIG_ENABLE_FKEY<
18b90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
18ba0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 is option is use
18bb0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 d to enable or d
18bc0 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 isable the enfor
18bd0 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f cement of.** [fo
18be0 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 reign key constr
18bf0 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 aints]. There s
18c00 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 hould be two add
18c10 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
18c20 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 s..** The first
18c30 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 argument is an i
18c40 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 nteger which is
18c50 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 0 to disable FK
18c60 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 enforcement,.**
18c70 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 positive to enab
18c80 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e le FK enforcemen
18c90 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f t or negative to
18ca0 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 leave FK enforc
18cb0 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 ement.** unchang
18cc0 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ed. The second
18cd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
18ce0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
18cf0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a eger into which.
18d00 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 ** is written 0
18d10 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 or 1 to indicate
18d20 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f whether FK enfo
18d30 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f rcement is off o
18d40 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e r on.** followin
18d50 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 g this call. Th
18d60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
18d70 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c er may be a NULL
18d80 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 pointer, in.**
18d90 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 which case the F
18da0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 K enforcement se
18db0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 tting is not rep
18dc0 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 orted back. </dd
18dd0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
18de0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
18df0 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a LE_TRIGGER</dt>.
18e00 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
18e10 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
18e20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
18e30 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 e [CREATE TRIGGE
18e40 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a R | triggers]..*
18e50 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 * There should b
18e60 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c e two additional
18e70 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 arguments..** T
18e80 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
18e90 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 t is an integer
18ea0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 which is 0 to di
18eb0 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a sable triggers,.
18ec0 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 ** positive to e
18ed0 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f nable triggers o
18ee0 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 r negative to le
18ef0 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 ave the setting
18f00 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 unchanged..** Th
18f10 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
18f20 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 er is a pointer
18f30 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e to an integer in
18f40 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 to which.** is w
18f50 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f ritten 0 or 1 to
18f60 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 indicate whethe
18f70 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 r triggers are d
18f80 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c isabled or enabl
18f90 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ed.** following
18fa0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 this call. The
18fb0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
18fc0 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 may be a NULL p
18fd0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 ointer, in.** wh
18fe0 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 ich case the tri
18ff0 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 gger setting is
19000 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 not reported bac
19010 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c k. </dd>.**.** <
19020 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
19030 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 IG_ENABLE_FTS3_T
19040 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a OKENIZER</dt>.**
19050 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
19060 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e on is used to en
19070 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 able or disable
19080 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 the two-argument
19090 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 .** version of t
190a0 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a he [fts3_tokeniz
190b0 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 er()] function w
190c0 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 hich is part of
190d0 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 the.** [FTS3] fu
190e0 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 ll-text search e
190f0 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e ngine extension.
19100 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 .** There should
19110 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e be two addition
19120 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a al arguments..**
19130 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
19140 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ent is an intege
19150 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 r which is 0 to
19160 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b disable fts3_tok
19170 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 enizer() or.** p
19180 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c ositive to enabl
19190 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 e fts3_tokenizer
191a0 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 () or negative t
191b0 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 o leave the sett
191c0 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 ing.** unchanged
191d0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
191e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
191f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
19200 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a eger into which.
19210 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 ** is written 0
19220 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 or 1 to indicate
19230 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f whether fts3_to
19240 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 kenizer is disab
19250 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a led or enabled.*
19260 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 * following this
19270 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f call. The seco
19280 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 nd parameter may
19290 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 be a NULL point
192a0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 er, in.** which
192b0 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 case the new set
192c0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f ting is not repo
192d0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e rted back. </dd>
192e0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
192f0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
19300 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e E_LOAD_EXTENSION
19310 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
19320 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 his option is us
19330 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 ed to enable or
19340 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c disable the [sql
19350 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 ite3_load_extens
19360 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 ion()].** interf
19370 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c ace independentl
19380 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 y of the [load_e
19390 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 xtension()] SQL
193a0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 function..** The
193b0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 [sqlite3_enable
193c0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
193d0 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f )] API enables o
193e0 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 r disables both
193f0 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 the.** C-API [sq
19400 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e lite3_load_exten
19410 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 sion()] and the
19420 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f SQL function [lo
19430 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e ad_extension()].
19440 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 .** There should
19450 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e be two addition
19460 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a al arguments..**
19470 20 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 When the first
19480 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 argument to this
19490 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c interface is 1,
194a0 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 then only the C
194b0 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c -API is.** enabl
194c0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 ed and the SQL f
194d0 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 unction remains
194e0 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 disabled. If th
194f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
19500 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 to.** this inte
19510 72 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e rface is 0, then
19520 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 both the C-API
19530 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 and the SQL func
19540 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 tion are disable
19550 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 d..** If the fir
19560 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d st argument is -
19570 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 1, then no chang
19580 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 es are made to s
19590 74 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 tate of either t
195a0 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 he.** C-API or t
195b0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e he SQL function.
195c0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 .** The second p
195d0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f arameter is a po
195e0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
195f0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a ger into which.*
19600 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f * is written 0 o
19610 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 r 1 to indicate
19620 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 whether [sqlite3
19630 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
19640 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 )] interface.**
19650 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 is disabled or e
19660 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 nabled following
19670 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 this call. The
19680 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
19690 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 r may.** be a NU
196a0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 LL pointer, in w
196b0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 hich case the ne
196c0 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 w setting is not
196d0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a reported back..
196e0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ** </dd>.**.** <
196f0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
19700 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 IG_MAINDBNAME</d
19710 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
19720 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 option is used
19730 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 to change the na
19740 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 me of the "main"
19750 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 database.** sch
19760 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 ema. ^The sole
19770 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f argument is a po
19780 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 inter to a const
19790 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a ant UTF8 string.
197a0 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 ** which will be
197b0 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 come the new sch
197c0 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 ema name in plac
197d0 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 e of "main". ^S
197e0 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f QLite.** does no
197f0 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 t make a copy of
19800 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 the new main sc
19810 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 hema name string
19820 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 , so the applica
19830 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 tion.** must ens
19840 75 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67 ure that the arg
19850 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 ument passed int
19860 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 o this DBCONFIG
19870 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e option is unchan
19880 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 ged.** until aft
19890 65 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 er the database
198a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 connection close
198b0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a s..** </dd>.**.*
198c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 * <dt>SQLITE_DBC
198d0 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e ONFIG_NO_CKPT_ON
198e0 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c _CLOSE</dt>.** <
198f0 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 dd> Usually, whe
19900 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 6e 20 n a database in
19910 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 wal mode is clos
19920 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 20 66 ed or detached f
19930 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 rom a .** databa
19940 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 se handle, SQLit
19950 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 69 73 e checks if this
19960 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 will mean that
19970 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f there are now no
19980 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 .** connections
19990 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 at all to the d
199a0 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 atabase. If so,
199b0 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68 it performs a ch
199c0 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 eckpoint .** ope
199d0 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c ration before cl
199e0 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 osing the connec
199f0 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f tion. This optio
19a00 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f n may be used to
19a10 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69 .** override thi
19a20 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65 s behaviour. The
19a30 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
19a40 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 passed to this
19a50 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 operation.** is
19a60 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 70 6f 73 an integer - pos
19a70 69 74 69 76 65 20 74 6f 20 64 69 73 61 62 6c 65 itive to disable
19a80 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d checkpoints-on-
19a90 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 close, or zero (
19aa0 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 the.** default)
19ab0 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2c 20 to enable them,
19ac0 61 6e 64 20 6e 65 67 61 74 69 76 65 20 74 6f 20 and negative to
19ad0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e leave the settin
19ae0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 g unchanged..**
19af0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
19b00 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 eter is a pointe
19b10 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a r to an integer.
19b20 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 ** into which is
19b30 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 written 0 or 1
19b40 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 to indicate whet
19b50 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d her checkpoints-
19b60 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 on-close.** have
19b70 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d been disabled -
19b80 20 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e 0 if they are n
19b90 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69 ot disabled, 1 i
19ba0 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c f they are..** <
19bb0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
19bc0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
19bd0 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a NABLE_QPSG</dt>.
19be0 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c ** <dd>^(The SQL
19bf0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
19c00 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20 BLE_QPSG option
19c10 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 activates or dea
19c20 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 ctivates.** the
19c30 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 73 [query planner s
19c40 74 61 62 69 6c 69 74 79 20 67 75 61 72 61 6e 74 tability guarant
19c50 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57 68 65 ee] (QPSG). Whe
19c60 6e 20 74 68 65 20 51 50 53 47 20 69 73 20 61 63 n the QPSG is ac
19c70 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c tive,.** a singl
19c80 65 20 53 51 4c 20 71 75 65 72 79 20 73 74 61 74 e SQL query stat
19c90 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79 ement will alway
19ca0 73 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 61 s use the same a
19cb0 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72 64 6c lgorithm regardl
19cc0 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73 ess.** of values
19cd0 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d of [bound param
19ce0 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 51 50 eters].)^ The QP
19cf0 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f 6d 65 SG disables some
19d00 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 61 74 query optimizat
19d10 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f ions.** that loo
19d20 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65 73 20 k at the values
19d30 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 of bound paramet
19d40 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e 20 6d ers, which can m
19d50 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 65 73 ake some queries
19d60 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 75 74 .** slower. But
19d70 20 74 68 65 20 51 50 53 47 20 68 61 73 20 74 68 the QPSG has th
19d80 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66 20 6d e advantage of m
19d90 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c 65 20 ore predictable
19da0 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74 68 0a behavior. With.
19db0 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63 74 69 ** the QPSG acti
19dc0 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 ve, SQLite will
19dd0 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20 73 always use the s
19de0 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e 20 69 ame query plan i
19df0 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73 0a 2a n the field as.*
19e00 2a 20 77 61 73 20 75 73 65 64 20 64 75 72 69 6e * was used durin
19e10 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74 68 65 g testing in the
19e20 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66 69 72 lab..** The fir
19e30 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
19e40 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 61 his setting is a
19e50 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 n integer which
19e60 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 is 0 to disable
19e70 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c 20 70 6f .** the QPSG, po
19e80 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 sitive to enable
19e90 20 51 50 53 47 2c 20 6f 72 20 6e 65 67 61 74 69 QPSG, or negati
19ea0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 ve to leave the
19eb0 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 setting.** uncha
19ec0 6e 67 65 64 2e 20 54 68 65 20 73 65 63 6f 6e 64 nged. The second
19ed0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
19ee0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
19ef0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 teger into which
19f00 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 .** is written 0
19f10 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 or 1 to indicat
19f20 65 20 77 68 65 74 68 65 72 20 74 68 65 20 51 50 e whether the QP
19f30 53 47 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f SG is disabled o
19f40 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c r enabled.** fol
19f50 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c lowing this call
19f60 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ..** </dd>.**.**
19f70 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
19f80 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 NFIG_TRIGGER_EQP
19f90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42 79 </dt>.** <dd> By
19fa0 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 6f 75 default, the ou
19fb0 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49 4e 20 tput of EXPLAIN
19fc0 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d 61 QUERY PLAN comma
19fd0 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a 2a 2a nds does not .**
19fe0 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75 74 20 include output
19ff0 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74 69 6f for any operatio
1a000 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 ns performed by
1a010 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 trigger programs
1a020 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f 6e . This.** option
1a030 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 is used to set
1a040 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20 64 65 or clear (the de
1a050 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20 74 68 fault) a flag th
1a060 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69 73 0a at governs this.
1a070 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54 68 65 ** behavior. The
1a080 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
1a090 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 passed to this
1a0a0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 operation is an
1a0b0 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70 6f 73 integer -.** pos
1a0c0 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 itive to enable
1a0d0 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69 67 67 output for trigg
1a0e0 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f 72 20 er programs, or
1a0f0 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 zero to disable
1a100 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61 74 69 it,.** or negati
1a110 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 ve to leave the
1a120 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 setting unchange
1a130 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 d..** The second
1a140 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
1a150 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
1a160 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 teger into which
1a170 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a 2a 20 is written .**
1a180 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 0 or 1 to indica
1a190 74 65 20 77 68 65 74 68 65 72 20 6f 75 74 70 75 te whether outpu
1a1a0 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73 20 68 t-for-triggers h
1a1b0 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 as been disabled
1a1c0 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74 20 69 - 0 if .** it i
1a1d0 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 s not disabled,
1a1e0 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a 2a 2a 1 if it is. .**
1a1f0 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a </dd>.** </dl>.
1a200 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1a210 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 E_DBCONFIG_MAIND
1a220 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 BNAME
1a230 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 1000 /* const c
1a240 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 har* */.#define
1a250 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
1a260 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 LOOKASIDE
1a270 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 1001 /* vo
1a280 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 id* int int */.#
1a290 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
1a2a0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b CONFIG_ENABLE_FK
1a2b0 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30 EY 100
1a2c0 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 2 /* int int* */
1a2d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1a2e0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
1a2f0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31 TRIGGER 1
1a300 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 003 /* int int*
1a310 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1a320 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
1a330 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 E_FTS3_TOKENIZER
1a340 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 1004 /* int int
1a350 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
1a360 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
1a370 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 BLE_LOAD_EXTENSI
1a380 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 ON 1005 /* int i
1a390 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nt* */.#define S
1a3a0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e QLITE_DBCONFIG_N
1a3b0 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 O_CKPT_ON_CLOSE
1a3c0 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 1006 /* int
1a3d0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 int* */.#define
1a3e0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
1a3f0 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 20 20 20 _ENABLE_QPSG
1a400 20 20 20 20 20 20 20 31 30 30 37 20 2f 2a 20 69 1007 /* i
1a410 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 nt int* */.#defi
1a420 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
1a430 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 20 20 IG_TRIGGER_EQP
1a440 20 20 20 20 20 20 20 20 20 31 30 30 38 20 2f 2a 1008 /*
1a450 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 int int* */.#de
1a460 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
1a470 4e 46 49 47 5f 4d 41 58 20 20 20 20 20 20 20 20 NFIG_MAX
1a480 20 20 20 20 20 20 20 20 20 20 20 31 30 30 38 20 1008
1a490 2f 2a 20 4c 61 72 67 65 73 74 20 44 42 43 4f 4e /* Largest DBCON
1a4a0 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 FIG */../*.** CA
1a4b0 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f PI3REF: Enable O
1a4c0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 r Disable Extend
1a4d0 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a ed Result Codes.
1a4e0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
1a4f0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 e3.**.** ^The sq
1a500 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 lite3_extended_r
1a510 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f esult_codes() ro
1a520 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 utine enables or
1a530 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a disables the.**
1a540 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
1a550 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 t codes] feature
1a560 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 of SQLite. ^The
1a570 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
1a580 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 .** codes are di
1a590 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
1a5a0 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c t for historical
1a5b0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a compatibility..
1a5c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 */.int sqlite3_e
1a5d0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 xtended_result_c
1a5e0 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 odes(sqlite3*, i
1a5f0 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a nt onoff);../*.*
1a600 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 * CAPI3REF: Last
1a610 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a Insert Rowid.**
1a620 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
1a630 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 .**.** ^Each ent
1a640 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 ry in most SQLit
1a650 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 e tables (except
1a660 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f for [WITHOUT RO
1a670 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 WID] tables).**
1a680 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d has a unique 64-
1a690 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e bit signed.** in
1a6a0 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 teger key called
1a6b0 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 the [ROWID | "r
1a6c0 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 owid"]. ^The row
1a6d0 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 id is always ava
1a6e0 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 ilable.** as an
1a6f0 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d undeclared colum
1a700 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f n named ROWID, O
1a710 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 ID, or _ROWID_ a
1a720 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a s long as those.
1a730 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 ** names are not
1a740 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 also used by ex
1a750 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 plicitly declare
1a760 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a d columns. ^If.*
1a770 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 * the table has
1a780 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 a column of type
1a790 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 [INTEGER PRIMAR
1a7a0 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 Y KEY] then that
1a7b0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e column.** is an
1a7c0 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 other alias for
1a7d0 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a the rowid..**.**
1a7e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 ^The sqlite3_la
1a7f0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
1a800 44 29 20 69 6e 74 65 72 66 61 63 65 20 75 73 75 D) interface usu
1a810 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 ally returns the
1a820 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20 74 [rowid] of.** t
1a830 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 he most recent s
1a840 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
1a850 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 T] into a rowid
1a860 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 table or [virtua
1a870 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 l table].** on d
1a880 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1a890 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73 20 69 on D. ^Inserts i
1a8a0 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 nto [WITHOUT ROW
1a8b0 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e ID] tables are n
1a8c0 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e 20 ot.** recorded.
1a8d0 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 ^If no successfu
1a8e0 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f l [INSERT]s into
1a8f0 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 68 61 rowid tables ha
1a900 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 ve ever occurred
1a910 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74 61 .** on the data
1a920 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1a930 44 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f D, then sqlite3_
1a940 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
1a950 64 28 44 29 20 72 65 74 75 72 6e 73 20 0a 2a 2a d(D) returns .**
1a960 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 zero..**.** As
1a970 77 65 6c 6c 20 61 73 20 62 65 69 6e 67 20 73 65 well as being se
1a980 74 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 t automatically
1a990 61 73 20 72 6f 77 73 20 61 72 65 20 69 6e 73 65 as rows are inse
1a9a0 72 74 65 64 20 69 6e 74 6f 20 64 61 74 61 62 61 rted into databa
1a9b0 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74 68 se.** tables, th
1a9c0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
1a9d0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f by this functio
1a9e0 6e 20 6d 61 79 20 62 65 20 73 65 74 20 65 78 70 n may be set exp
1a9f0 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b 73 licitly by.** [s
1aa00 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f qlite3_set_last_
1aa10 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a insert_rowid()].
1aa20 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74 75 **.** Some virtu
1aa30 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 al table impleme
1aa40 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e 53 ntations may INS
1aa50 45 52 54 20 72 6f 77 73 20 69 6e 74 6f 20 72 6f ERT rows into ro
1aa60 77 69 64 20 74 61 62 6c 65 73 20 61 73 0a 2a 2a wid tables as.**
1aa70 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74 74 part of committ
1aa80 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f ing a transactio
1aa90 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73 68 n (e.g. to flush
1aaa0 20 64 61 74 61 20 61 63 63 75 6d 75 6c 61 74 65 data accumulate
1aab0 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 74 d in memory.** t
1aac0 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74 68 69 73 o disk). In this
1aad0 20 63 61 73 65 20 73 75 62 73 65 71 75 65 6e 74 case subsequent
1aae0 20 63 61 6c 6c 73 20 74 6f 20 74 68 69 73 20 66 calls to this f
1aaf0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 20 74 unction return t
1ab00 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73 6f he rowid.** asso
1ab10 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 73 ciated with thes
1ab20 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45 52 e internal INSER
1ab30 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77 68 T operations, wh
1ab40 69 63 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a 2a ich leads to .**
1ab50 20 75 6e 69 6e 74 75 69 74 69 76 65 20 72 65 73 unintuitive res
1ab60 75 6c 74 73 2e 20 56 69 72 74 75 61 6c 20 74 61 ults. Virtual ta
1ab70 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
1ab80 6f 6e 73 20 74 68 61 74 20 64 6f 20 77 72 69 74 ons that do writ
1ab90 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74 61 e to rowid.** ta
1aba0 62 6c 65 73 20 69 6e 20 74 68 69 73 20 77 61 79 bles in this way
1abb0 20 63 61 6e 20 61 76 6f 69 64 20 74 68 69 73 20 can avoid this
1abc0 70 72 6f 62 6c 65 6d 20 62 79 20 72 65 73 74 6f problem by resto
1abd0 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 ring the origina
1abe0 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c 75 l .** rowid valu
1abf0 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 e using [sqlite3
1ac00 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 _set_last_insert
1ac10 5f 72 6f 77 69 64 28 29 5d 20 62 65 66 6f 72 65 _rowid()] before
1ac20 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20 63 returning .** c
1ac30 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20 75 73 ontrol to the us
1ac40 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 er..**.** ^(If a
1ac50 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 n [INSERT] occur
1ac60 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 s within a trigg
1ac70 65 72 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 er then this rou
1ac80 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72 65 tine will .** re
1ac90 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d turn the [rowid]
1aca0 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 of the inserted
1acb0 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 row as long as
1acc0 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20 0a the trigger is .
1acd0 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63 65 ** running. Once
1ace0 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f the trigger pro
1acf0 67 72 61 6d 20 65 6e 64 73 2c 20 74 68 65 20 76 gram ends, the v
1ad00 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a alue returned .*
1ad10 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e * by this routin
1ad20 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 e reverts to wha
1ad30 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 t it was before
1ad40 74 68 65 20 74 72 69 67 67 65 72 20 77 61 73 20 the trigger was
1ad50 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e fired.)^.**.** ^
1ad60 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 An [INSERT] that
1ad70 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 fails due to a
1ad80 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
1ad90 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a tion is not a.**
1ada0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 successful [INS
1adb0 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f ERT] and does no
1adc0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c t change the val
1add0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 ue returned by t
1ade0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 his.** routine.
1adf0 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 ^Thus INSERT OR
1ae00 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 FAIL, INSERT OR
1ae10 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 IGNORE, INSERT
1ae20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 OR ROLLBACK,.**
1ae30 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 and INSERT OR AB
1ae40 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e ORT make no chan
1ae50 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 ges to the retur
1ae60 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a n value of this.
1ae70 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 ** routine when
1ae80 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 their insertion
1ae90 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 fails. ^(When I
1aea0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 NSERT OR REPLACE
1aeb0 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 .** encounters a
1aec0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c constraint viol
1aed0 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e ation, it does n
1aee0 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a ot fail. The.**
1aef0 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 INSERT continue
1af00 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 s to completion
1af10 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 after deleting r
1af20 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a ows that caused.
1af30 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e ** the constrain
1af40 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 t problem so INS
1af50 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 ERT OR REPLACE w
1af60 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 ill always chang
1af70 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 e.** the return
1af80 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e value of this in
1af90 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a terface.)^.**.**
1afa0 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 ^For the purpos
1afb0 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 es of this routi
1afc0 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 ne, an [INSERT]
1afd0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f is considered to
1afe0 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 .** be successfu
1aff0 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 l even if it is
1b000 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c subsequently rol
1b010 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 led back..**.**
1b020 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 This function is
1b030 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 accessible to S
1b040 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 QL statements vi
1b050 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 a the.** [last_i
1b060 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 nsert_rowid() SQ
1b070 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a L function]..**.
1b080 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 ** If a separate
1b090 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 thread performs
1b0a0 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 a new [INSERT]
1b0b0 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 on the same.** d
1b0c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1b0d0 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 on while the [sq
1b0e0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
1b0f0 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 t_rowid()].** fu
1b100 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
1b110 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 g and thus chang
1b120 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 es the last inse
1b130 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 rt [rowid],.** t
1b140 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
1b150 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
1b160 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
1b170 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e owid()] is.** un
1b180 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 predictable and
1b190 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 might not equal
1b1a0 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f either the old o
1b1b0 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 r the new.** las
1b1c0 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d t insert [rowid]
1b1d0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 ..*/.sqlite3_int
1b1e0 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 64 sqlite3_last_
1b1f0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c insert_rowid(sql
1b200 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
1b210 41 50 49 33 52 45 46 3a 20 53 65 74 20 74 68 65 API3REF: Set the
1b220 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 Last Insert Row
1b230 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45 54 id value..** MET
1b240 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
1b250 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 ** The sqlite3_s
1b260 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 et_last_insert_r
1b270 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74 68 6f owid(D, R) metho
1b280 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 70 70 d allows the app
1b290 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 73 lication to.** s
1b2a0 65 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 et the value ret
1b2b0 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 urned by calling
1b2c0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e sqlite3_last_in
1b2d0 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 74 6f sert_rowid(D) to
1b2e0 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20 69 R .** without i
1b2f0 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77 20 69 nserting a row i
1b300 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 nto the database
1b310 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
1b320 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 3_set_last_inser
1b330 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a t_rowid(sqlite3*
1b340 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b ,sqlite3_int64);
1b350 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1b360 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 : Count The Numb
1b370 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 er Of Rows Modif
1b380 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ied.** METHOD: s
1b390 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
1b3a0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
1b3b0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
1b3c0 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c f rows modified,
1b3d0 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 inserted or.**
1b3e0 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d deleted by the m
1b3f0 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d ost recently com
1b400 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 pleted INSERT, U
1b410 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a PDATE or DELETE.
1b420 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 ** statement on
1b430 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
1b440 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 nection specifie
1b450 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 d by the only pa
1b460 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 rameter..** ^Exe
1b470 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 cuting any other
1b480 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 type of SQL sta
1b490 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 tement does not
1b4a0 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 modify the value
1b4b0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 .** returned by
1b4c0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a this function..*
1b4d0 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 *.** ^Only chang
1b4e0 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 es made directly
1b4f0 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 by the INSERT,
1b500 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 UPDATE or DELETE
1b510 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a statement are.*
1b520 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 * considered - a
1b530 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 uxiliary changes
1b540 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 caused by [CREA
1b550 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 TE TRIGGER | tri
1b560 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 ggers], .** [for
1b570 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 eign key actions
1b580 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 ] or [REPLACE] c
1b590 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 onstraint resolu
1b5a0 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 tion are not cou
1b5b0 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 nted..** .** Cha
1b5c0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 nges to a view t
1b5d0 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 hat are intercep
1b5e0 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 ted by .** [INST
1b5f0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c EAD OF trigger |
1b600 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 INSTEAD OF trig
1b610 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f gers] are not co
1b620 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 unted. ^The valu
1b630 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 e .** returned b
1b640 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 y sqlite3_change
1b650 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 s() immediately
1b660 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c after an INSERT,
1b670 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 UPDATE or .** D
1b680 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 ELETE statement
1b690 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 run on a view is
1b6a0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e always zero. On
1b6b0 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 ly changes made
1b6c0 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c to real .** tabl
1b6d0 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a es are counted..
1b6e0 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 **.** Things are
1b6f0 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 more complicate
1b700 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 d if the sqlite3
1b710 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 _changes() funct
1b720 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 ion is.** execut
1b730 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 ed while a trigg
1b740 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 er program is ru
1b750 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 nning. This may
1b760 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a happen if the.**
1b770 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 program uses th
1b780 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c e [changes() SQL
1b790 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 function], or i
1b7a0 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c f some other cal
1b7b0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f lback.** functio
1b7c0 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 n invokes sqlite
1b7d0 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 3_changes() dire
1b7e0 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c ctly. Essentiall
1b7f0 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a y:.** .** <ul>.*
1b800 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 * <li> ^(Befor
1b810 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 e entering a tri
1b820 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 gger program the
1b830 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
1b840 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c by.** sql
1b850 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 ite3_changes() f
1b860 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 unction is saved
1b870 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67 . After the trig
1b880 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 ger program .**
1b890 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 has finis
1b8a0 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 hed, the origina
1b8b0 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f l value is resto
1b8c0 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 red.)^.** .**
1b8d0 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 <li> ^(Within a
1b8e0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 trigger program
1b8f0 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 each INSERT, UPD
1b900 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a ATE and DELETE .
1b910 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d ** statem
1b920 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c ent sets the val
1b930 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ue returned by s
1b940 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
1b950 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e .** upon
1b960 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e completion as n
1b970 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 ormal. Of course
1b980 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c , this value wil
1b990 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a l not include .*
1b9a0 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 * any cha
1b9b0 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 nges performed b
1b9c0 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 y sub-triggers,
1b9d0 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 as the sqlite3_c
1b9e0 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 hanges() .**
1b9f0 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 value will b
1ba00 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 e saved and rest
1ba10 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20 ored after each
1ba20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 sub-trigger has
1ba30 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a run.)^.** </ul>.
1ba40 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 ** .** ^This mea
1ba50 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63 ns that if the c
1ba60 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e hanges() SQL fun
1ba70 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 ction (or simila
1ba80 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 r) is used.** by
1ba90 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 the first INSER
1baa0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c T, UPDATE or DEL
1bab0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 ETE statement wi
1bac0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 thin a trigger,
1bad0 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 it .** returns t
1bae0 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 he value as set
1baf0 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 when the calling
1bb00 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e statement began
1bb10 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e executing..** ^
1bb20 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79 If it is used by
1bb30 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 the second or s
1bb40 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 ubsequent such s
1bb50 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 tatement within
1bb60 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 a trigger .** pr
1bb70 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 ogram, the value
1bb80 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 returned reflec
1bb90 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ts the number of
1bba0 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 rows modified b
1bbb0 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f y the .** previo
1bbc0 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 us INSERT, UPDAT
1bbd0 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 E or DELETE stat
1bbe0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 ement within the
1bbf0 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a same trigger..*
1bc00 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 *.** See also th
1bc10 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c e [sqlite3_total
1bc20 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 _changes()] inte
1bc30 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 rface, the.** [c
1bc40 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 ount_changes pra
1bc50 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 gma], and the [c
1bc60 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e hanges() SQL fun
1bc70 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 ction]..**.** If
1bc80 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
1bc90 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 ad makes changes
1bca0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 on the same dat
1bcb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1bcc0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 .** while [sqlit
1bcd0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 e3_changes()] is
1bce0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 running then th
1bcf0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
1bd00 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 .** is unpredict
1bd10 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 able and not mea
1bd20 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 ningful..*/.int
1bd30 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
1bd40 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
1bd50 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 * CAPI3REF: Tota
1bd60 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 l Number Of Rows
1bd70 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 Modified.** MET
1bd80 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
1bd90 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
1bda0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f n returns the to
1bdb0 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f tal number of ro
1bdc0 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 ws inserted, mod
1bdd0 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 ified or.** dele
1bde0 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 ted by all [INSE
1bdf0 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 RT], [UPDATE] or
1be00 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d [DELETE] statem
1be10 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a ents completed.*
1be20 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 * since the data
1be30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1be40 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c was opened, incl
1be50 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 uding those exec
1be60 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 uted as.** part
1be70 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 of trigger progr
1be80 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 ams. ^Executing
1be90 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f any other type o
1bea0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a f SQL statement.
1beb0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 ** does not affe
1bec0 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ct the value ret
1bed0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
1bee0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
1bef0 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 ..** .** ^Change
1bf00 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f s made as part o
1bf10 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 f [foreign key a
1bf20 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c ctions] are incl
1bf30 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 uded in the.** c
1bf40 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 ount, but those
1bf50 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 made as part of
1bf60 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 REPLACE constrai
1bf70 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 nt resolution ar
1bf80 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 e.** not. ^Chang
1bf90 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 es to a view tha
1bfa0 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 t are intercepte
1bfb0 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 d by INSTEAD OF
1bfc0 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 triggers .** are
1bfd0 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a not counted..**
1bfe0 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 .** See also th
1bff0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 e [sqlite3_chang
1c000 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c es()] interface,
1c010 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 the.** [count_c
1c020 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 hanges pragma],
1c030 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 and the [total_c
1c040 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e hanges() SQL fun
1c050 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 ction]..**.** If
1c060 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
1c070 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 ad makes changes
1c080 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 on the same dat
1c090 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1c0a0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 .** while [sqlit
1c0b0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
1c0c0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
1c0d0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a hen the value.**
1c0e0 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 returned is unp
1c0f0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e redictable and n
1c100 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a ot meaningful..*
1c110 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f /.int sqlite3_to
1c120 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 tal_changes(sqli
1c130 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
1c140 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 PI3REF: Interrup
1c150 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 t A Long-Running
1c160 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 Query.** METHOD
1c170 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
1c180 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 ^This function c
1c190 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e auses any pendin
1c1a0 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 g database opera
1c1b0 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e tion to abort an
1c1c0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 d.** return at i
1c1d0 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f ts earliest oppo
1c1e0 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f rtunity. This ro
1c1f0 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c utine is typical
1c200 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 ly.** called in
1c210 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 response to a us
1c220 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 er action such a
1c230 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 s pressing "Canc
1c240 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 el".** or Ctrl-C
1c250 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 where the user
1c260 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 wants a long que
1c270 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 ry operation to
1c280 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 halt.** immediat
1c290 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 ely..**.** ^It i
1c2a0 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 s safe to call t
1c2b0 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d his routine from
1c2c0 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 a thread differ
1c2d0 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 ent from the.**
1c2e0 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 thread that is c
1c2f0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 urrently running
1c300 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 the database op
1c310 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 eration. But it
1c320 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 .** is not safe
1c330 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 to call this rou
1c340 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 tine with a [dat
1c350 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1c360 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f ] that.** is clo
1c370 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f sed or might clo
1c380 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 se before sqlite
1c390 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 3_interrupt() re
1c3a0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 turns..**.** ^If
1c3b0 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f an SQL operatio
1c3c0 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 n is very nearly
1c3d0 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 finished at the
1c3e0 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 time when.** sq
1c3f0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
1c400 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 ) is called, the
1c410 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 n it might not h
1c420 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 ave an opportuni
1c430 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 ty.** to be inte
1c440 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 rrupted and migh
1c450 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f t continue to co
1c460 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 mpletion..**.**
1c470 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f ^An SQL operatio
1c480 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 n that is interr
1c490 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 upted will retur
1c4a0 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 n [SQLITE_INTERR
1c4b0 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 UPT]..** ^If the
1c4c0 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c interrupted SQL
1c4d0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e operation is an
1c4e0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
1c4f0 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 or DELETE.** th
1c500 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 at is inside an
1c510 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 explicit transac
1c520 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 tion, then the e
1c530 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f ntire transactio
1c540 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c n.** will be rol
1c550 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 led back automat
1c560 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ically..**.** ^T
1c570 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
1c580 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 rupt(D) call is
1c590 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 in effect until
1c5a0 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 all currently ru
1c5b0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 nning.** SQL sta
1c5c0 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 tements on [data
1c5d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1c5e0 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 D complete. ^A
1c5f0 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 ny new SQL state
1c600 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 ments.** that ar
1c610 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 e started after
1c620 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 the sqlite3_inte
1c630 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 rrupt() call and
1c640 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 before the .**
1c650 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e running statemen
1c660 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 ts reaches zero
1c670 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 are interrupted
1c680 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 as if they had b
1c690 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 een.** running p
1c6a0 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 rior to the sqli
1c6b0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
1c6c0 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 call. ^New SQL
1c6d0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 statements.** th
1c6e0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 at are started a
1c6f0 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 fter the running
1c700 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 statement count
1c710 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 reaches zero ar
1c720 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 e.** not effecte
1c730 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 d by the sqlite3
1c740 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a _interrupt()..**
1c750 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ^A call to sqli
1c760 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 te3_interrupt(D)
1c770 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 that occurs whe
1c780 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 n there are no r
1c790 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 unning.** SQL st
1c7a0 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f atements is a no
1c7b0 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 -op and has no e
1c7c0 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 ffect on SQL sta
1c7d0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 tements.** that
1c7e0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 are started afte
1c7f0 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e r the sqlite3_in
1c800 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 terrupt() call r
1c810 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69 64 20 eturns..*/.void
1c820 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
1c830 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a t(sqlite3*);../*
1c840 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
1c850 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 termine If An SQ
1c860 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 L Statement Is C
1c870 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 omplete.**.** Th
1c880 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
1c890 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 useful during c
1c8a0 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 ommand-line inpu
1c8b0 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 t to determine i
1c8c0 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 f the.** current
1c8d0 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 ly entered text
1c8e0 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 seems to form a
1c8f0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 complete SQL sta
1c900 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 tement or.** if
1c910 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 additional input
1c920 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 is needed befor
1c930 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 e sending the te
1c940 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 xt into.** SQLit
1c950 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 e for parsing.
1c960 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
1c970 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 return 1 if the
1c980 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 input string.**
1c990 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 appears to be a
1c9a0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 complete SQL sta
1c9b0 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 tement. ^A stat
1c9c0 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 ement is judged
1c9d0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 to be.** complet
1c9e0 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 e if it ends wit
1c9f0 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f h a semicolon to
1ca00 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 ken and is not a
1ca10 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 prefix of a.**
1ca20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 well-formed CREA
1ca30 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 TE TRIGGER state
1ca40 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f ment. ^Semicolo
1ca50 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 ns that are embe
1ca60 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 dded within.** s
1ca70 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f tring literals o
1ca80 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 r quoted identif
1ca90 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d ier names or com
1caa0 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a ments are not.**
1cab0 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b independent tok
1cac0 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 ens (they are pa
1cad0 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 rt of the token
1cae0 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 in which they ar
1caf0 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 e.** embedded) a
1cb00 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 nd thus do not c
1cb10 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d ount as a statem
1cb20 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ent terminator.
1cb30 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 ^Whitespace.**
1cb40 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 and comments tha
1cb50 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e t follow the fin
1cb60 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 al semicolon are
1cb70 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 ignored..**.**
1cb80 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
1cb90 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 return 0 if the
1cba0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 statement is inc
1cbb0 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a omplete. ^If a.
1cbc0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
1cbd0 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e tion fails, then
1cbe0 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 SQLITE_NOMEM is
1cbf0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
1cc00 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
1cc10 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 do not parse th
1cc20 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
1cc30 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f thus.** will no
1cc40 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 t detect syntact
1cc50 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 ically incorrect
1cc60 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 SQL..**.** ^(If
1cc70 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 SQLite has not
1cc80 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 been initialized
1cc90 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
1cca0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 initialize()] pr
1ccb0 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b ior .** to invok
1ccc0 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 ing sqlite3_comp
1ccd0 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 lete16() then sq
1cce0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
1ccf0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a () is invoked.**
1cd00 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 automatically b
1cd10 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 y sqlite3_comple
1cd20 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 te16(). If that
1cd30 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
1cd40 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 fails,.** then t
1cd50 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
1cd60 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d from sqlite3_com
1cd70 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 plete16() will b
1cd80 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 e non-zero.** re
1cd90 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
1cda0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 her or not the i
1cdb0 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 nput SQL is comp
1cdc0 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 lete.)^.**.** Th
1cdd0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 e input to [sqli
1cde0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 te3_complete()]
1cdf0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 must be a zero-t
1ce00 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 erminated.** UTF
1ce10 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a -8 string..**.**
1ce20 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 The input to [s
1ce30 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
1ce40 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 6()] must be a z
1ce50 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
1ce60 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 * UTF-16 string
1ce70 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f in native byte o
1ce80 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c rder..*/.int sql
1ce90 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f ite3_complete(co
1cea0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a nst char *sql);.
1ceb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 int sqlite3_comp
1cec0 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 lete16(const voi
1ced0 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 d *sql);../*.**
1cee0 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 CAPI3REF: Regist
1cef0 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f er A Callback To
1cf00 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 Handle SQLITE_B
1cf10 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 USY Errors.** KE
1cf20 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 YWORDS: {busy-ha
1cf30 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 ndler callback}
1cf40 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a {busy handler}.*
1cf50 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
1cf60 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 3.**.** ^The sql
1cf70 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
1cf80 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 r(D,X,P) routine
1cf90 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b sets a callback
1cfa0 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 function X.** t
1cfb0 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 hat might be inv
1cfc0 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 oked with argume
1cfd0 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a nt P whenever.**
1cfe0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d an attempt is m
1cff0 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 ade to access a
1d000 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 database table a
1d010 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a ssociated with.*
1d020 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
1d030 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 ection] D when a
1d040 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a nother thread.**
1d050 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 or process has
1d060 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 the table locked
1d070 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 ..** The sqlite3
1d080 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 _busy_handler()
1d090 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
1d0a0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a d to implement.*
1d0b0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f * [sqlite3_busy_
1d0c0 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b timeout()] and [
1d0d0 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 PRAGMA busy_time
1d0e0 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 out]..**.** ^If
1d0f0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 the busy callbac
1d100 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 k is NULL, then
1d110 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a [SQLITE_BUSY].**
1d120 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d is returned imm
1d130 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e ediately upon en
1d140 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c countering the l
1d150 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 ock. ^If the bu
1d160 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 sy callback.** i
1d170 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e s not NULL, then
1d180 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 the callback mi
1d190 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 ght be invoked w
1d1a0 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 ith two argument
1d1b0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 s..**.** ^The fi
1d1c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
1d1d0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
1d1e0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
1d1f0 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 e void* pointer
1d200 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 which.** is the
1d210 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 third argument t
1d220 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 o sqlite3_busy_h
1d230 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 andler(). ^The
1d240 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
1d250 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 to.** the busy h
1d260 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 andler callback
1d270 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
1d280 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 times that the
1d290 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 busy handler has
1d2a0 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 .** been invoked
1d2b0 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 previously for
1d2c0 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 the same locking
1d2d0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 event. ^If the
1d2e0 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 .** busy callbac
1d2f0 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 k returns 0, the
1d300 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 n no additional
1d310 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 attempts are mad
1d320 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 e to.** access t
1d330 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 he database and
1d340 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 [SQLITE_BUSY] is
1d350 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 returned.** to
1d360 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e the application.
1d370 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c .** ^If the call
1d380 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e back returns non
1d390 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 -zero, then anot
1d3a0 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 her attempt.** i
1d3b0 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 s made to access
1d3c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e the database an
1d3d0 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 d the cycle repe
1d3e0 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 ats..**.** The p
1d3f0 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 resence of a bus
1d400 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e y handler does n
1d410 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 ot guarantee tha
1d420 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 t it will be inv
1d430 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 oked.** when the
1d440 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 re is lock conte
1d450 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 ntion. ^If SQLit
1d460 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 e determines tha
1d470 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 t invoking the b
1d480 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 usy.** handler c
1d490 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 ould result in a
1d4a0 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 deadlock, it wi
1d4b0 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 ll go ahead and
1d4c0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 return [SQLITE_B
1d4d0 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 USY].** to the a
1d4e0 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 pplication inste
1d4f0 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 ad of invoking t
1d500 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 he .** busy hand
1d510 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 ler..** Consider
1d520 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 a scenario wher
1d530 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 e one process is
1d540 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 holding a read
1d550 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 lock that.** it
1d560 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f is trying to pro
1d570 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 mote to a reserv
1d580 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 ed lock and.** a
1d590 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
1d5a0 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 is holding a res
1d5b0 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 erved lock that
1d5c0 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 it is trying.**
1d5d0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e to promote to an
1d5e0 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e exclusive lock.
1d5f0 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 The first proc
1d600 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 ess cannot proce
1d610 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 ed.** because it
1d620 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 is blocked by t
1d630 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 he second and th
1d640 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 e second process
1d650 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 cannot.** proce
1d660 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 ed because it is
1d670 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 blocked by the
1d680 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 first. If both
1d690 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 processes.** inv
1d6a0 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e oke the busy han
1d6b0 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 dlers, neither w
1d6c0 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f ill make any pro
1d6d0 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 gress. Therefor
1d6e0 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 e,.** SQLite ret
1d6f0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 urns [SQLITE_BUS
1d700 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 Y] for the first
1d710 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 process, hoping
1d720 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 that this.** wi
1d730 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 ll induce the fi
1d740 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 rst process to r
1d750 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 elease its read
1d760 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a lock and allow.*
1d770 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f * the second pro
1d780 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e cess to proceed.
1d790 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 .**.** ^The defa
1d7a0 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 ult busy callbac
1d7b0 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a k is NULL..**.**
1d7c0 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c ^(There can onl
1d7d0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 y be a single bu
1d7e0 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e sy handler defin
1d7f0 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b ed for each.** [
1d800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1d810 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 ion]. Setting a
1d820 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 new busy handle
1d830 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 r clears any.**
1d840 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 previously set h
1d850 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 andler.)^ ^Note
1d860 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 that calling [s
1d870 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 qlite3_busy_time
1d880 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 out()].** or eva
1d890 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 luating [PRAGMA
1d8a0 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 busy_timeout=N]
1d8b0 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a will change the.
1d8c0 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 ** busy handler
1d8d0 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 and thus clear a
1d8e0 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 ny previously se
1d8f0 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a t busy handler..
1d900 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 **.** The busy c
1d910 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e allback should n
1d920 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 ot take any acti
1d930 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 ons which modify
1d940 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
1d950 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
1d960 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 invoked the bus
1d970 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f y handler. In o
1d980 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 ther words,.** t
1d990 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
1d9a0 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 is not reentrant
1d9b0 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 . Any such acti
1d9c0 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e ons.** result in
1d9d0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
1d9e0 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 ior..** .** A bu
1d9f0 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 sy handler must
1da00 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 not close the da
1da10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1da20 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 n.** or [prepare
1da30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
1da40 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 t invoked the bu
1da50 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 sy handler..*/.i
1da60 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f nt sqlite3_busy_
1da70 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a handler(sqlite3*
1da80 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e ,int(*)(void*,in
1da90 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a t),void*);../*.*
1daa0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 * CAPI3REF: Set
1dab0 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a A Busy Timeout.*
1dac0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
1dad0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 3.**.** ^This ro
1dae0 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 utine sets a [sq
1daf0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
1db00 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 er | busy handle
1db10 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a r] that sleeps.*
1db20 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 * for a specifie
1db30 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 d amount of time
1db40 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 when a table is
1db50 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 locked. ^The h
1db60 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 andler.** will s
1db70 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 leep multiple ti
1db80 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 mes until at lea
1db90 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 st "ms" millisec
1dba0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 onds of sleeping
1dbb0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c .** have accumul
1dbc0 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 ated. ^After at
1dbd0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c least "ms" mill
1dbe0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 iseconds of slee
1dbf0 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e ping,.** the han
1dc00 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 dler returns 0 w
1dc10 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c hich causes [sql
1dc20 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 ite3_step()] to
1dc30 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 return.** [SQLIT
1dc40 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e E_BUSY]..**.** ^
1dc50 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 Calling this rou
1dc60 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 tine with an arg
1dc70 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 ument less than
1dc80 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f or equal to zero
1dc90 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c .** turns off al
1dca0 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e l busy handlers.
1dcb0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 .**.** ^(There c
1dcc0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e an only be a sin
1dcd0 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 gle busy handler
1dce0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
1dcf0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 r.** [database c
1dd00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e onnection] at an
1dd10 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 y given moment.
1dd20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 If another busy
1dd30 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 handler.** was
1dd40 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 defined (using
1dd50 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 [sqlite3_busy_ha
1dd60 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 ndler()]) prior
1dd70 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 to calling.** th
1dd80 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 is routine, that
1dd90 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 other busy hand
1dda0 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 ler is cleared.)
1ddb0 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ^.**.** See also
1ddc0 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f : [PRAGMA busy_
1ddd0 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 timeout].*/.int
1dde0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
1ddf0 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 eout(sqlite3*, i
1de00 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 nt ms);../*.** C
1de10 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 API3REF: Conveni
1de20 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f ence Routines Fo
1de30 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 r Running Querie
1de40 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
1de50 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ite3.**.** This
1de60 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 is a legacy inte
1de70 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 rface that is pr
1de80 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b eserved for back
1de90 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
1dea0 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 ity..** Use of t
1deb0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
1dec0 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 not recommended
1ded0 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 ..**.** Definiti
1dee0 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 on: A <b>result
1def0 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d table</b> is mem
1df00 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 ory data structu
1df10 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 re created by th
1df20 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 e.** [sqlite3_ge
1df30 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 t_table()] inter
1df40 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 face. A result
1df50 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 table records th
1df60 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 e.** complete qu
1df70 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d ery results from
1df80 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 one or more que
1df90 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ries..**.** The
1dfa0 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c table conceptual
1dfb0 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 ly has a number
1dfc0 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 of rows and colu
1dfd0 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 mns. But.** the
1dfe0 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e se numbers are n
1dff0 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 ot part of the r
1e000 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 esult table itse
1e010 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 lf. These.** nu
1e020 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e mbers are obtain
1e030 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 ed separately.
1e040 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d Let N be the num
1e050 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 ber of rows.** a
1e060 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 nd M be the numb
1e070 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a er of columns..*
1e080 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 *.** A result ta
1e090 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 ble is an array
1e0a0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a of pointers to z
1e0b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
1e0c0 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a TF-8 strings..**
1e0d0 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 There are (N+1)
1e0e0 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 *M elements in t
1e0f0 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 he array. The f
1e100 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 irst M pointers
1e110 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f point.** to zero
1e120 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
1e130 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 ngs that contai
1e140 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 n the names of t
1e150 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 he columns..** T
1e160 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 he remaining ent
1e170 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 ries all point t
1e180 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e o query results.
1e190 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 NULL values re
1e1a0 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 sult.** in NULL
1e1b0 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f pointers. All o
1e1c0 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 ther values are
1e1d0 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a in their UTF-8 z
1e1e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
1e1f0 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 * string represe
1e200 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 ntation as retur
1e210 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
1e220 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a column_text()]..
1e230 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 **.** A result t
1e240 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 able might consi
1e250 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 st of one or mor
1e260 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
1e270 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e ions..** It is n
1e280 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 ot safe to pass
1e290 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 a result table d
1e2a0 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 irectly to [sqli
1e2b0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 te3_free()]..**
1e2c0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 A result table s
1e2d0 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 hould be dealloc
1e2e0 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ated using [sqli
1e2f0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
1e300 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e ]..**.** ^(As an
1e310 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 example of the
1e320 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 result table for
1e330 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 mat, suppose a q
1e340 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 uery result.** i
1e350 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a s as follows:.**
1e360 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
1e370 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <pre>.**
1e380 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 Name | Ag
1e390 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d e.** ----
1e3a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1e3b0 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c ---.** Al
1e3c0 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a ice | 43.*
1e3d0 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 * Bob
1e3e0 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 | 28.**
1e3f0 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 Cindy
1e400 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f | 21.** </pre></
1e410 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
1e420 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 * There are two
1e430 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e column (M==2) an
1e440 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d d three rows (N=
1e450 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a =3). Thus the.*
1e460 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 * result table h
1e470 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 as 8 entries. S
1e480 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c uppose the resul
1e490 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 t table is store
1e4a0 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 d.** in an array
1e4b0 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e names azResult.
1e4c0 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 Then azResult
1e4d0 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 holds this conte
1e4e0 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b nt:.**.** <block
1e4f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1e500 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
1e510 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 91;0] = "Name";.
1e520 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1e530 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 lt[1] = "Age
1e540 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1e550 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 esult[2] = "
1e560 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 Alice";.**
1e570 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 azResult[3
1e580 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 ] = "43";.**
1e590 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1e5a0 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 ;4] = "Bob";.**
1e5b0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
1e5c0 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a #91;5] = "28";.*
1e5d0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1e5e0 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 t[6] = "Cind
1e5f0 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a y";.** az
1e600 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 Result[7] =
1e610 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c "21";.** </pre><
1e620 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a /blockquote>)^.*
1e630 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1e640 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 3_get_table() fu
1e650 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 nction evaluates
1e660 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 one or more.**
1e670 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 semicolon-separa
1e680 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ted SQL statemen
1e690 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 ts in the zero-t
1e6a0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a erminated UTF-8.
1e6b0 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 ** string of its
1e6c0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
1e6d0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 nd returns a res
1e6e0 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 ult table to the
1e6f0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 .** pointer give
1e700 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 n in its 3rd par
1e710 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 ameter..**.** Af
1e720 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 ter the applicat
1e730 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 ion has finished
1e740 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 with the result
1e750 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 from sqlite3_ge
1e760 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 t_table(),.** it
1e770 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 must pass the r
1e780 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e esult table poin
1e790 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 ter to sqlite3_f
1e7a0 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f ree_table() in o
1e7b0 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 rder to.** relea
1e7c0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 se the memory th
1e7d0 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e at was malloced.
1e7e0 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 Because of the
1e7f0 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c way the.** [sql
1e800 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 ite3_malloc()] h
1e810 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 appens within sq
1e820 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1e830 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a ), the calling.*
1e840 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 * function must
1e850 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 not try to call
1e860 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1e870 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 directly. Only
1e880 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
1e890 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 e_table()] is ab
1e8a0 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 le to release th
1e8b0 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c e memory properl
1e8c0 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a y and safely..**
1e8d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
1e8e0 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 get_table() inte
1e8f0 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 rface is impleme
1e900 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 nted as a wrappe
1e910 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c r around.** [sql
1e920 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 ite3_exec()]. T
1e930 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
1e940 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 able() routine d
1e950 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 oes not have acc
1e960 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e ess.** to any in
1e970 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 ternal data stru
1e980 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 ctures of SQLite
1e990 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 . It uses only
1e9a0 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e the public.** in
1e9b0 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 terface defined
1e9c0 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 here. As a cons
1e9d0 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 equence, errors
1e9e0 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 that occur in th
1e9f0 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 e.** wrapper lay
1ea00 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 er outside of th
1ea10 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 e internal [sqli
1ea20 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c te3_exec()] call
1ea30 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c are not.** refl
1ea40 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 ected in subsequ
1ea50 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ent calls to [sq
1ea60 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
1ea70 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
1ea80 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e errmsg()]..*/.in
1ea90 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 t sqlite3_get_ta
1eaa0 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ble(. sqlite3 *
1eab0 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 db, /*
1eac0 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 An open database
1ead0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
1eae0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 *zSql, /* S
1eaf0 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 QL to be evaluat
1eb00 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a ed */. char ***
1eb10 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a pazResult, /*
1eb20 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 Results of the
1eb30 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a query */. int *
1eb40 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 pnRow,
1eb50 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 /* Number of re
1eb60 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 sult rows writte
1eb70 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 n here */. int
1eb80 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 *pnColumn,
1eb90 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 /* Number of r
1eba0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 esult columns wr
1ebb0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 itten here */.
1ebc0 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 char **pzErrmsg
1ebd0 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d /* Error m
1ebe0 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 sg written here
1ebf0 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 */.);.void sqlit
1ec00 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 e3_free_table(ch
1ec10 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f ar **result);../
1ec20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
1ec30 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 ormatted String
1ec40 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f Printing Functio
1ec50 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 ns.**.** These r
1ec60 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b outines are work
1ec70 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 -alikes of the "
1ec80 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 printf()" family
1ec90 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a of functions.**
1eca0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 from the standa
1ecb0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a rd C library..**
1ecc0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1ecd0 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 understand most
1ece0 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 66 6f of the common fo
1ecf0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 rmatting options
1ed00 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 from.** the sta
1ed10 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 70 72 ndard library pr
1ed20 69 6e 74 66 28 29 20 0a 2a 2a 20 70 6c 75 73 20 intf() .** plus
1ed30 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 some additional
1ed40 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 non-standard for
1ed50 6d 61 74 73 20 28 5b 25 71 5d 2c 20 5b 25 51 5d mats ([%q], [%Q]
1ed60 2c 20 5b 25 77 5d 2c 20 61 6e 64 20 5b 25 7a 5d , [%w], and [%z]
1ed70 29 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 62 )..** See the [b
1ed80 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 uilt-in printf()
1ed90 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 ] documentation
1eda0 66 6f 72 20 64 65 74 61 69 6c 73 2e 0a 2a 2a 0a for details..**.
1edb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1edc0 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 mprintf() and sq
1edd0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 lite3_vmprintf()
1ede0 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 routines write
1edf0 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 their.** results
1ee00 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 into memory obt
1ee10 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
1ee20 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 2e te3_malloc64()].
1ee30 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 .** The strings
1ee40 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 returned by thes
1ee50 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 e two routines s
1ee60 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 hould be.** rele
1ee70 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ased by [sqlite3
1ee80 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 _free()]. ^Both
1ee90 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
1eea0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 a.** NULL point
1eeb0 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d er if [sqlite3_m
1eec0 61 6c 6c 6f 63 36 34 28 29 5d 20 69 73 20 75 6e alloc64()] is un
1eed0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 able to allocate
1eee0 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 enough.** memor
1eef0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 y to hold the re
1ef00 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a sulting string..
1ef10 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 **.** ^(The sqli
1ef20 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 te3_snprintf() r
1ef30 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 outine is simila
1ef40 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 r to "snprintf()
1ef50 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 " from.** the st
1ef60 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
1ef70 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 . The result is
1ef80 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
1ef90 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 e.** buffer supp
1efa0 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f lied as the seco
1efb0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f nd parameter who
1efc0 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e se size is given
1efd0 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 by.** the first
1efe0 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 parameter. Note
1eff0 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 that the order
1f000 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 of the.** first
1f010 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 two parameters i
1f020 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 s reversed from
1f030 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 snprintf().)^ T
1f040 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 his is an.** his
1f050 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 torical accident
1f060 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 that cannot be
1f070 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 fixed without br
1f080 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 eaking.** backwa
1f090 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
1f0a0 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 y. ^(Note also
1f0b0 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 that sqlite3_snp
1f0c0 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 rintf().** retur
1f0d0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
1f0e0 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 its buffer inste
1f0f0 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 ad of the number
1f100 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 of.** character
1f110 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 s actually writt
1f120 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 en into the buff
1f130 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 er.)^ We admit
1f140 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 that.** the numb
1f150 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
1f160 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 written would b
1f170 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 e a more useful
1f180 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 return.** value
1f190 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 but we cannot ch
1f1a0 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 ange the impleme
1f1b0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 ntation of sqlit
1f1c0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
1f1d0 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 now without bre
1f1e0 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c aking compatibil
1f1f0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c ity..**.** ^As l
1f200 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 ong as the buffe
1f210 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 r size is greate
1f220 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c r than zero, sql
1f230 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a ite3_snprintf().
1f240 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 ** guarantees th
1f250 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 at the buffer is
1f260 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 always zero-ter
1f270 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 minated. ^The f
1f280 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 irst.** paramete
1f290 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 r "n" is the tot
1f2a0 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 al size of the b
1f2b0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 uffer, including
1f2c0 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 space for.** th
1f2d0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f e zero terminato
1f2e0 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 r. So the longe
1f2f0 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 st string that c
1f300 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 an be completely
1f310 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c .** written will
1f320 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 be n-1 characte
1f330 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 rs..**.** ^The s
1f340 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 qlite3_vsnprintf
1f350 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 () routine is a
1f360 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 varargs version
1f370 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 of sqlite3_snpri
1f380 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 ntf()..**.** See
1f390 20 61 6c 73 6f 3a 20 20 5b 62 75 69 6c 74 2d 69 also: [built-i
1f3a0 6e 20 70 72 69 6e 74 66 28 29 5d 2c 20 5b 70 72 n printf()], [pr
1f3b0 69 6e 74 66 28 29 20 53 51 4c 20 66 75 6e 63 74 intf() SQL funct
1f3c0 69 6f 6e 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 ion].*/.char *sq
1f3d0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f lite3_mprintf(co
1f3e0 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a nst char*,...);.
1f3f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d char *sqlite3_vm
1f400 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 printf(const cha
1f410 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 r*, va_list);.ch
1f420 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 ar *sqlite3_snpr
1f430 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 intf(int,char*,c
1f440 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 onst char*, ...)
1f450 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f ;.char *sqlite3_
1f460 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 vsnprintf(int,ch
1f470 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
1f480 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a va_list);../*.*
1f490 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f * CAPI3REF: Memo
1f4a0 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 ry Allocation Su
1f4b0 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 bsystem.**.** Th
1f4c0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 e SQLite core us
1f4d0 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 es these three r
1f4e0 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 outines for all
1f4f0 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e of its own.** in
1f500 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c ternal memory al
1f510 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 location needs.
1f520 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 "Core" in the pr
1f530 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a evious sentence.
1f540 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c ** does not incl
1f550 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 ude operating-sy
1f560 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 stem specific VF
1f570 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
1f580 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 . The.** Window
1f590 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 s VFS uses nativ
1f5a0 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 e malloc() and f
1f5b0 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f ree() for some o
1f5c0 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a perations..**.**
1f5d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 ^The sqlite3_ma
1f5e0 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 lloc() routine r
1f5f0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
1f600 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f to a block.** o
1f610 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 f memory at leas
1f620 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e t N bytes in len
1f630 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 gth, where N is
1f640 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a the parameter..*
1f650 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 * ^If sqlite3_ma
1f660 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 lloc() is unable
1f670 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 to obtain suffi
1f680 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 cient free.** me
1f690 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 mory, it returns
1f6a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
1f6b0 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 ^If the parame
1f6c0 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 ter N to.** sqli
1f6d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 te3_malloc() is
1f6e0 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 zero or negative
1f6f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 then sqlite3_ma
1f700 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a lloc() returns.*
1f710 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 * a NULL pointer
1f720 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
1f730 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 ite3_malloc64(N)
1f740 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a routine works j
1f750 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 ust like.** sqli
1f760 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 te3_malloc(N) ex
1f770 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 cept that N is a
1f780 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 n unsigned 64-bi
1f790 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 t integer instea
1f7a0 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 d.** of a signed
1f7b0 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 32-bit integer.
1f7c0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 .**.** ^Calling
1f7d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 sqlite3_free() w
1f7e0 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 ith a pointer pr
1f7f0 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 eviously returne
1f800 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f d.** by sqlite3_
1f810 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 malloc() or sqli
1f820 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 te3_realloc() re
1f830 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f leases that memo
1f840 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 ry so.** that it
1f850 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 might be reused
1f860 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
1f870 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 free() routine i
1f880 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 s.** a no-op if
1f890 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 is called with a
1f8a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 NULL pointer.
1f8b0 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 Passing a NULL p
1f8c0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c ointer.** to sql
1f8d0 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 ite3_free() is h
1f8e0 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 armless. After
1f8f0 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d being freed, mem
1f900 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 ory.** should ne
1f910 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f ither be read no
1f920 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e r written. Even
1f930 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 reading previou
1f940 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d sly freed.** mem
1f950 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 ory might result
1f960 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 in a segmentati
1f970 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 on fault or othe
1f980 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a r severe error..
1f990 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 ** Memory corrup
1f9a0 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 tion, a segmenta
1f9b0 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f tion fault, or o
1f9c0 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f ther severe erro
1f9d0 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c r.** might resul
1f9e0 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 t if sqlite3_fre
1f9f0 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 e() is called wi
1fa00 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f th a non-NULL po
1fa10 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 inter that.** wa
1fa20 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 s not obtained f
1fa30 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c rom sqlite3_mall
1fa40 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f oc() or sqlite3_
1fa50 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a realloc()..**.**
1fa60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
1fa70 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 alloc(X,N) inter
1fa80 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f face attempts to
1fa90 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 resize a.** pri
1faa0 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 or memory alloca
1fab0 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 tion X to be at
1fac0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a least N bytes..*
1fad0 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 * ^If the X para
1fae0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
1faf0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a _realloc(X,N).**
1fb00 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
1fb10 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 er then its beha
1fb20 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 vior is identica
1fb30 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 l to calling.**
1fb40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e sqlite3_malloc(N
1fb50 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 )..** ^If the N
1fb60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
1fb70 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e ite3_realloc(X,N
1fb80 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 ) is zero or.**
1fb90 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 negative then th
1fba0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 e behavior is ex
1fbb0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 actly the same a
1fbc0 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c s calling.** sql
1fbd0 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a ite3_free(X)..**
1fbe0 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f ^sqlite3_reallo
1fbf0 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 c(X,N) returns a
1fc00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 pointer to a me
1fc10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a mory allocation.
1fc20 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e ** of at least N
1fc30 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f bytes in size o
1fc40 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 r NULL if insuff
1fc50 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 icient memory is
1fc60 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e available..** ^
1fc70 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 If M is the size
1fc80 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c of the prior al
1fc90 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d location, then m
1fca0 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a in(N,M) bytes.**
1fcb0 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c of the prior al
1fcc0 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 location are cop
1fcd0 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 ied into the beg
1fce0 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 inning of buffer
1fcf0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 returned.** by
1fd00 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1fd10 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 X,N) and the pri
1fd20 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 or allocation is
1fd30 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 freed..** ^If s
1fd40 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 qlite3_realloc(X
1fd50 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c ,N) returns NULL
1fd60 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 and N is positi
1fd70 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 ve, then the.**
1fd80 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
1fd90 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a is not freed..*
1fda0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1fdb0 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 3_realloc64(X,N)
1fdc0 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b interfaces work
1fdd0 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a s the same as.**
1fde0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1fdf0 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 (X,N) except tha
1fe00 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 t N is a 64-bit
1fe10 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 unsigned integer
1fe20 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 instead.** of a
1fe30 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 32-bit signed i
1fe40 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 nteger..**.** ^I
1fe50 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 f X is a memory
1fe60 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 allocation previ
1fe70 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 ously obtained f
1fe80 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c rom sqlite3_mall
1fe90 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 oc(),.** sqlite3
1fea0 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c _malloc64(), sql
1feb0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 ite3_realloc(),
1fec0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c or sqlite3_reall
1fed0 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 oc64(), then.**
1fee0 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 sqlite3_msize(X)
1fef0 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a returns the siz
1ff00 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 e of that memory
1ff10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 allocation in b
1ff20 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 ytes..** ^The va
1ff30 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
1ff40 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 sqlite3_msize(X)
1ff50 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 might be larger
1ff60 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 than the number
1ff70 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 .** of bytes req
1ff80 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 uested when X wa
1ff90 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 s allocated. ^I
1ffa0 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f f X is a NULL po
1ffb0 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 inter then.** sq
1ffc0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 lite3_msize(X) r
1ffd0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 eturns zero. If
1ffe0 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d X points to som
1fff0 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e ething that is n
20000 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e ot.** the beginn
20010 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c ing of memory al
20020 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 location, or if
20030 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 it points to a f
20040 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 ormerly.** valid
20050 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
20060 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 on that has now
20070 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e been freed, then
20080 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a the behavior.**
20090 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a of sqlite3_msiz
200a0 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 e(X) is undefine
200b0 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 d and possibly h
200c0 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 armful..**.** ^T
200d0 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e he memory return
200e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 ed by sqlite3_ma
200f0 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f lloc(), sqlite3_
20100 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 realloc(),.** sq
20110 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 lite3_malloc64()
20120 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 , and sqlite3_re
20130 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 alloc64().** is
20140 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 always aligned t
20150 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 o at least an 8
20160 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f byte boundary, o
20170 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 r to a.** 4 byte
20180 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 boundary if the
20190 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f [SQLITE_4_BYTE_
201a0 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 ALIGNED_MALLOC]
201b0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 compile-time.**
201c0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a option is used..
201d0 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 **.** In SQLite
201e0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e version 3.5.0 an
201f0 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 d 3.5.1, it was
20200 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 possible to defi
20210 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 ne.** the SQLITE
20220 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c _OMIT_MEMORY_ALL
20230 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f OCATION which wo
20240 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 uld cause the bu
20250 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d ilt-in.** implem
20260 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 entation of thes
20270 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 e routines to be
20280 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 omitted. That
20290 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 capability.** is
202a0 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 no longer provi
202b0 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 ded. Only built
202c0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 -in memory alloc
202d0 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 ators can be use
202e0 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 d..**.** Prior t
202f0 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e o SQLite version
20300 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 3.7.10, the Win
20310 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 dows OS interfac
20320 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a e layer called.*
20330 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c * the system mal
20340 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 loc() and free()
20350 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 directly when c
20360 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c onverting.** fil
20370 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 enames between t
20380 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e he UTF-8 encodin
20390 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 g used by SQLite
203a0 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 .** and whatever
203b0 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 filename encodi
203c0 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 ng is used by th
203d0 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e e particular Win
203e0 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 dows.** installa
203f0 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c tion. Memory al
20400 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 location errors
20410 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 were detected, b
20420 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 ut.** they were
20430 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 reported back as
20440 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 [SQLITE_CANTOPE
20450 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 N] or.** [SQLITE
20460 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 _IOERR] rather t
20470 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 han [SQLITE_NOME
20480 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f M]..**.** The po
20490 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 inter arguments
204a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 to [sqlite3_free
204b0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
204c0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d _realloc()].** m
204d0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 ust be either NU
204e0 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 LL or else point
204f0 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ers obtained fro
20500 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 m a prior.** inv
20510 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 ocation of [sqli
20520 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 te3_malloc()] or
20530 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
20540 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a c()] that have.*
20550 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 * not yet been r
20560 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 eleased..**.** T
20570 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
20580 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 ust not read or
20590 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f write any part o
205a0 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 f.** a block of
205b0 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 memory after it
205c0 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 has been release
205d0 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 d using.** [sqli
205e0 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b te3_free()] or [
205f0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
20600 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c )]..*/.void *sql
20610 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 ite3_malloc(int)
20620 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f ;.void *sqlite3_
20630 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 malloc64(sqlite3
20640 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a _uint64);.void *
20650 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
20660 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 void*, int);.voi
20670 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c d *sqlite3_reall
20680 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 oc64(void*, sqli
20690 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 te3_uint64);.voi
206a0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 d sqlite3_free(v
206b0 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 oid*);.sqlite3_u
206c0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 int64 sqlite3_ms
206d0 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a ize(void*);../*.
206e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d ** CAPI3REF: Mem
206f0 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 ory Allocator St
20700 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 atistics.**.** S
20710 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 QLite provides t
20720 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 hese two interfa
20730 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e ces for reportin
20740 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a g on the status.
20750 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
20760 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 e3_malloc()], [s
20770 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 qlite3_free()],
20780 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 and [sqlite3_rea
20790 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 lloc()].** routi
207a0 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 nes, which form
207b0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d the built-in mem
207c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 ory allocation s
207d0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 ubsystem..**.**
207e0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 ^The [sqlite3_me
207f0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 mory_used()] rou
20800 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
20810 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
20820 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 .** of memory cu
20830 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 rrently outstand
20840 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 ing (malloced bu
20850 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a t not freed)..**
20860 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d ^The [sqlite3_m
20870 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
20880 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 )] routine retur
20890 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a ns the maximum.*
208a0 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 * value of [sqli
208b0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
208c0 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 )] since the hig
208d0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 h-water mark.**
208e0 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 was last reset.
208f0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 ^The values ret
20900 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
20910 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
20920 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
20930 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
20940 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 r()] include any
20950 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 overhead.** add
20960 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 ed by SQLite in
20970 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 its implementati
20980 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d on of [sqlite3_m
20990 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 alloc()],.** but
209a0 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 not overhead ad
209b0 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 ded by the any u
209c0 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d nderlying system
209d0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 library.** rout
209e0 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 ines that [sqlit
209f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 e3_malloc()] may
20a00 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 call..**.** ^Th
20a10 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 e memory high-wa
20a20 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 ter mark is rese
20a30 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 t to the current
20a40 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 value of.** [sq
20a50 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
20a60 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 d()] if and only
20a70 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
20a80 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 r to.** [sqlite3
20a90 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
20aa0 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e r()] is true. ^
20ab0 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e The value return
20ac0 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 ed.** by [sqlite
20ad0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
20ae0 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 er(1)] is the hi
20af0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a gh-water mark.**
20b00 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 prior to the re
20b10 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f set..*/.sqlite3_
20b20 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 int64 sqlite3_me
20b30 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b mory_used(void);
20b40 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
20b50 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
20b60 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 ghwater(int rese
20b70 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 tFlag);../*.** C
20b80 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d API3REF: Pseudo-
20b90 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 Random Number Ge
20ba0 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 nerator.**.** SQ
20bb0 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 Lite contains a
20bc0 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 high-quality pse
20bd0 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 udo-random numbe
20be0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e r generator (PRN
20bf0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 G) used to.** se
20c00 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 lect random [ROW
20c10 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 ID | ROWIDs] whe
20c20 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 n inserting new
20c30 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 records into a t
20c40 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 able that.** alr
20c50 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 eady uses the la
20c60 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b rgest possible [
20c70 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e ROWID]. The PRN
20c80 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 G is also used f
20c90 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d or.** the build-
20ca0 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 in random() and
20cb0 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c randomblob() SQL
20cc0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 functions. Thi
20cd0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f s interface allo
20ce0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f ws.** applicatio
20cf0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 ns to access the
20d00 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f same PRNG for o
20d10 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a ther purposes..*
20d20 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 *.** ^A call to
20d30 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f this routine sto
20d40 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 res N bytes of r
20d50 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 andomness into b
20d60 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 uffer P..** ^The
20d70 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e P parameter can
20d80 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 be a NULL point
20d90 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 er..**.** ^If th
20da0 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e is routine has n
20db0 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 ot been previous
20dc0 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 ly called or if
20dd0 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 the previous.**
20de0 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 call had N less
20df0 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 than one or a NU
20e00 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 LL pointer for P
20e10 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 , then the PRNG
20e20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 is.** seeded usi
20e30 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 ng randomness ob
20e40 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 tained from the
20e50 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 xRandomness meth
20e60 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 od of.** the def
20e70 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
20e80 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 s] object..** ^I
20e90 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 f the previous c
20ea0 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 all to this rout
20eb0 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 ine had an N of
20ec0 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 1 or more and a.
20ed0 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 ** non-NULL P th
20ee0 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 en the pseudo-ra
20ef0 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 ndomness is gene
20f00 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 rated.** interna
20f10 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 lly and without
20f20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 recourse to the
20f30 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 [sqlite3_vfs] xR
20f40 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 andomness.** met
20f50 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c hod..*/.void sql
20f60 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 ite3_randomness(
20f70 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b int N, void *P);
20f80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
20f90 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 : Compile-Time A
20fa0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c uthorization Cal
20fb0 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 lbacks.** METHOD
20fc0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 : sqlite3.** KEY
20fd0 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a WORDS: {authoriz
20fe0 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a er callback}.**.
20ff0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
21000 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 registers an au
21010 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
21020 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 k with a particu
21030 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 lar.** [database
21040 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 connection], su
21050 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 pplied in the fi
21060 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a rst argument..**
21070 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 ^The authorizer
21080 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
21090 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 oked as SQL stat
210a0 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 ements are being
210b0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 compiled.** by
210c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
210d0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 ()] or its varia
210e0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 nts [sqlite3_pre
210f0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b pare_v2()],.** [
21100 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
21110 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f v3()], [sqlite3_
21120 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73 prepare16()], [s
21130 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
21140 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b _v2()],.** and [
21150 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
21160 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61 6_v3()]. ^At va
21170 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 rious.** points
21180 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 during the compi
21190 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 lation process,
211a0 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e as logic is bein
211b0 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 g created.** to
211c0 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 perform various
211d0 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 actions, the aut
211e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
211f0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a is invoked to.*
21200 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 * see if those a
21210 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 ctions are allow
21220 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 ed. ^The author
21230 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 izer callback sh
21240 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b ould.** return [
21250 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c SQLITE_OK] to al
21260 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 low the action,
21270 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
21280 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a to disallow the.
21290 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 ** specific acti
212a0 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 on but allow the
212b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
212c0 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 o continue to be
212d0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 .** compiled, or
212e0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 [SQLITE_DENY] t
212f0 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 o cause the enti
21300 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 re SQL statement
21310 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 to be.** reject
21320 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 ed with an error
21330 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f . ^If the autho
21340 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 rizer callback r
21350 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 eturns.** any va
21360 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b lue other than [
21370 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 SQLITE_IGNORE],
21380 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 [SQLITE_OK], or
21390 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a [SQLITE_DENY].**
213a0 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 then the [sqlit
213b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
213c0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 or equivalent c
213d0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
213e0 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 ed.** the author
213f0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 izer will fail w
21400 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 ith an error mes
21410 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e sage..**.** When
21420 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
21430 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
21440 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 ], that means th
21450 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 e operation.** r
21460 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 equested is ok.
21470 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 ^When the callb
21480 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ack returns [SQL
21490 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a ITE_DENY], the.*
214a0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
214b0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 re_v2()] or equi
214c0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 valent call that
214d0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a triggered the.*
214e0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c * authorizer wil
214f0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 l fail with an e
21500 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 rror message exp
21510 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 laining that.**
21520 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 access is denied
21530 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 . .**.** ^The fi
21540 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
21550 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
21560 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f callback is a co
21570 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a py of the third.
21580 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ** parameter to
21590 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f the sqlite3_set_
215a0 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 authorizer() int
215b0 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 erface. ^The sec
215c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ond parameter.**
215d0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
215e0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b is an integer [
215f0 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 SQLITE_COPY | ac
21600 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 tion code] that
21610 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 specifies.** the
21620 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 particular acti
21630 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 on to be authori
21640 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 zed. ^The third
21650 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 through sixth pa
21660 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 rameters.** to t
21670 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 he callback are
21680 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e either NULL poin
21690 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72 ters or zero-ter
216a0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a minated strings.
216b0 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 ** that contain
216c0 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 additional detai
216d0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 ls about the act
216e0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 ion to be author
216f0 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 ized..** Applica
21700 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79 tions must alway
21710 73 20 62 65 20 70 72 65 70 61 72 65 64 20 74 6f s be prepared to
21720 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c encounter a NUL
21730 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79 L pointer in any
21740 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64 .** of the third
21750 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 69 78 through the six
21760 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 th parameters of
21770 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 the authorizati
21780 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a on callback..**.
21790 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f ** ^If the actio
217a0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 n code is [SQLIT
217b0 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 E_READ].** and t
217c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
217d0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f rns [SQLITE_IGNO
217e0 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 RE] then the.**
217f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
21800 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 ent] statement i
21810 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f s constructed to
21820 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 substitute.** a
21830 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 NULL value in p
21840 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c lace of the tabl
21850 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f e column that wo
21860 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e uld have.** been
21870 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 read if [SQLITE
21880 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 _OK] had been re
21890 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 turned. The [SQ
218a0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 LITE_IGNORE].**
218b0 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 return can be us
218c0 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e ed to deny an un
218d0 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 trusted user acc
218e0 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 ess to individua
218f0 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 l.** columns of
21900 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 a table..** ^Whe
21910 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72 65 66 n a table is ref
21920 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45 erenced by a [SE
21930 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c LECT] but no col
21940 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a umn values are.*
21950 2a 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d * extracted from
21960 20 74 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72 that table (for
21970 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75 example in a qu
21980 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c ery like.** "SEL
21990 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f ECT count(*) FRO
219a0 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74 68 65 M tab") then the
219b0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 [SQLITE_READ] a
219c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
219d0 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 ck.** is invoked
219e0 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74 once for that t
219f0 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75 able with a colu
21a00 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 mn name that is
21a10 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e an empty string.
21a20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 .** ^If the acti
21a30 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 on code is [SQLI
21a40 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 TE_DELETE] and t
21a50 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
21a60 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 rns.** [SQLITE_I
21a70 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 GNORE] then the
21a80 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 [DELETE] operati
21a90 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 on proceeds but
21aa0 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 the.** [truncate
21ab0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 optimization] i
21ac0 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 s disabled and a
21ad0 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 ll rows are dele
21ae0 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 ted individually
21af0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f ..**.** An autho
21b00 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 rizer is used wh
21b10 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 en [sqlite3_prep
21b20 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d are | preparing]
21b30 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
21b40 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 ts from an untru
21b50 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 sted source, to
21b60 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 ensure that the
21b70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
21b80 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 * do not try to
21b90 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 access data they
21ba0 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 are not allowed
21bb0 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 to see, or that
21bc0 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 they do not.**
21bd0 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d try to execute m
21be0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 alicious stateme
21bf0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 nts that damage
21c00 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 the database. F
21c10 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 or.** example, a
21c20 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 n application ma
21c30 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 y allow a user t
21c40 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 o enter arbitrar
21c50 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 y.** SQL queries
21c60 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 for evaluation
21c70 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 by a database.
21c80 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 But the applicat
21c90 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 ion does.** not
21ca0 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f want the user to
21cb0 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 be able to make
21cc0 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 arbitrary chang
21cd0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 es to the.** dat
21ce0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f abase. An autho
21cf0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e rizer could then
21d00 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 be put in place
21d10 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 while the.** us
21d20 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 er-entered SQL i
21d30 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 s being [sqlite3
21d40 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 _prepare | prepa
21d50 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 red] that.** dis
21d60 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e allows everythin
21d70 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 g except [SELECT
21d80 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a ] statements..**
21d90 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 .** Applications
21da0 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 that need to pr
21db0 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 ocess SQL from u
21dc0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 ntrusted sources
21dd0 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 .** might also c
21de0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 onsider lowering
21df0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 resource limits
21e00 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
21e10 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 limit()].** and
21e20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 limiting databas
21e30 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 e size using the
21e40 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 [max_page_count
21e50 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e ] [PRAGMA].** in
21e60 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 addition to usi
21e70 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 ng an authorizer
21e80 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 ..**.** ^(Only a
21e90 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a single authoriz
21ea0 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 er can be in pla
21eb0 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 ce on a database
21ec0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 connection.** a
21ed0 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 t a time. Each
21ee0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
21ef0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f set_authorizer o
21f00 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 verrides the.**
21f10 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e previous call.)^
21f20 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 ^Disable the a
21f30 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 uthorizer by ins
21f40 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 talling a NULL c
21f50 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 allback..** The
21f60 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 authorizer is di
21f70 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
21f80 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 t..**.** The aut
21f90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
21fa0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 must not do any
21fb0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 thing that will
21fc0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 modify.** the da
21fd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
21fe0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 n that invoked t
21ff0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
22000 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 llback..** Note
22010 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 that [sqlite3_pr
22020 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
22030 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
22040 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 both modify the
22050 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ir.** database c
22060 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
22070 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
22080 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
22090 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 aragraph..**.**
220a0 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 ^When [sqlite3_p
220b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 repare_v2()] is
220c0 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 used to prepare
220d0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 a statement, the
220e0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 .** statement mi
220f0 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 ght be re-prepar
22100 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 ed during [sqlit
22110 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 e3_step()] due t
22120 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 o a .** schema c
22130 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 hange. Hence, t
22140 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
22150 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 hould ensure tha
22160 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 t the.** correct
22170 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
22180 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 back remains in
22190 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 place during the
221a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
221b0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 ]..**.** ^Note t
221c0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a hat the authoriz
221d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
221e0 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 nvoked only duri
221f0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 ng.** [sqlite3_p
22200 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 repare()] or its
22210 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 variants. Auth
22220 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 orization is not
22230 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 .** performed du
22240 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 ring statement e
22250 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 valuation in [sq
22260 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 lite3_step()], u
22270 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 nless.** as stat
22280 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f ed in the previo
22290 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 us paragraph, sq
222a0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 lite3_step() inv
222b0 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f okes.** sqlite3_
222c0 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 prepare_v2() to
222d0 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 reprepare a stat
222e0 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 ement after a sc
222f0 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a hema change..*/.
22300 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f int sqlite3_set_
22310 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 authorizer(. sq
22320 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a lite3*,. int (*
22330 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 xAuth)(void*,int
22340 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e ,const char*,con
22350 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 st char*,const c
22360 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
22370 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 ),. void *pUser
22380 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 Data.);../*.** C
22390 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 API3REF: Authori
223a0 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 zer Return Codes
223b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 .**.** The [sqli
223c0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
223d0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 er | authorizer
223e0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
223f0 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 n] must.** retur
22400 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 n either [SQLITE
22410 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 _OK] or one of t
22420 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e hese two constan
22430 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 ts in order.** t
22440 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 o signal SQLite
22450 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
22460 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 he action is per
22470 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 mitted. See the
22480 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 .** [sqlite3_set
22490 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 _authorizer | au
224a0 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e thorizer documen
224b0 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 tation] for addi
224c0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d tional.** inform
224d0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 ation..**.** Not
224e0 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 e that SQLITE_IG
224f0 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 NORE is also use
22500 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 d as a [conflict
22510 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 resolution mode
22520 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 ].** returned fr
22530 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f om the [sqlite3_
22540 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 vtab_on_conflict
22550 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
22560 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22570 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 _DENY 1 /* A
22580 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 bort the SQL sta
22590 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 tement with an e
225a0 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
225b0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 SQLITE_IGNORE 2
225c0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 /* Don't allow
225d0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e access, but don
225e0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 't generate an e
225f0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 rror */../*.** C
22600 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 API3REF: Authori
22610 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 zer Action Codes
22620 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 .**.** The [sqli
22630 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
22640 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 er()] interface
22650 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c registers a call
22660 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a back function.**
22670 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 that is invoked
22680 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 to authorize ce
22690 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d rtain SQL statem
226a0 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 ent actions. Th
226b0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 e.** second para
226c0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c meter to the cal
226d0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 lback is an inte
226e0 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 ger code that sp
226f0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 ecifies.** what
22700 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 action is being
22710 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 authorized. The
22720 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 se are the integ
22730 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 er action codes
22740 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 that.** the auth
22750 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
22760 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a may be passed..*
22770 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f *.** These actio
22780 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 n code values si
22790 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 gnify what kind
227a0 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 of operation is
227b0 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 to be.** authori
227c0 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e zed. The 3rd an
227d0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 d 4th parameters
227e0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
227f0 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 ation.** callbac
22800 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 k function will
22810 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 be parameters or
22820 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 NULL depending
22830 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 on which of thes
22840 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 e.** codes is us
22850 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
22860 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 parameter. ^(T
22870 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
22880 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f to the.** autho
22890 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
228a0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
228b0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 e database ("mai
228c0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 n", "temp",.** e
228d0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 tc.) if applicab
228e0 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 le.)^ ^The 6th
228f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
22900 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
22910 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e back.** is the n
22920 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 ame of the inner
22930 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 -most trigger or
22940 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 view that is re
22950 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a sponsible for.**
22960 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 the access atte
22970 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 mpt or NULL if t
22980 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d his access attem
22990 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 pt is directly f
229a0 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c rom.** top-level
229b0 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a SQL code..*/./*
229c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
229d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
229e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a ********** 3rd *
229f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 *********** 4th
22a00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 ***********/.#de
22a10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
22a20 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 TE_INDEX
22a30 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 1 /* Index N
22a40 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
22a50 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
22a60 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
22a70 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 E_TABLE
22a80 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 2 /* Table Na
22a90 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
22aa0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
22ab0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
22ac0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 _TEMP_INDEX
22ad0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 3 /* Index Nam
22ae0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
22af0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
22b00 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
22b10 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 TEMP_TABLE 4
22b20 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
22b30 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
22b40 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
22b50 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
22b60 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 EMP_TRIGGER 5
22b70 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
22b80 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
22b90 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22ba0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
22bb0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 MP_VIEW 6
22bc0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
22bd0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
22be0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
22bf0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 QLITE_CREATE_TRI
22c00 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 GGER 7
22c10 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
22c20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
22c30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
22c40 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 LITE_CREATE_VIEW
22c50 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 8 /
22c60 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
22c70 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
22c80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22c90 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 ITE_DELETE
22ca0 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 9 /*
22cb0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
22cc0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
22cd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22ce0 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 TE_DROP_INDEX
22cf0 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 10 /*
22d00 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
22d10 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
22d20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
22d30 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 E_DROP_TABLE
22d40 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 11 /* T
22d50 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
22d60 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
22d70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22d80 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 _DROP_TEMP_INDEX
22d90 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 12 /* In
22da0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
22db0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
22dc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22dd0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 DROP_TEMP_TABLE
22de0 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 13 /* Tab
22df0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
22e00 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
22e10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
22e20 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 ROP_TEMP_TRIGGER
22e30 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 14 /* Trig
22e40 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
22e50 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
22e60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
22e70 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 OP_TEMP_VIEW
22e80 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 15 /* View
22e90 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
22ea0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
22eb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
22ec0 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 P_TRIGGER
22ed0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 16 /* Trigge
22ee0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
22ef0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
22f00 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
22f10 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 _VIEW
22f20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 17 /* View Na
22f30 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
22f40 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
22f50 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 ine SQLITE_INSER
22f60 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
22f70 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 18 /* Table Na
22f80 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
22f90 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
22fa0 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 ne SQLITE_PRAGMA
22fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
22fc0 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 9 /* Pragma Na
22fd0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f me 1st arg o
22fe0 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e r NULL */.#defin
22ff0 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 e SQLITE_READ
23000 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20
23010 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
23020 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d Column Nam
23030 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
23040 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 SQLITE_SELECT
23050 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 21
23060 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 /* NULL
23070 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
23080 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
23090 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 SQLITE_TRANSACTI
230a0 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 ON 22
230b0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 /* Operation
230c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
230d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
230e0 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 QLITE_UPDATE
230f0 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 23
23100 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
23110 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 Column Name
23120 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
23130 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 LITE_ATTACH
23140 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 24 /
23150 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 * Filename
23160 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
23170 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
23180 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 ITE_DETACH
23190 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 25 /*
231a0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 Database Name
231b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
231c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
231d0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 TE_ALTER_TABLE
231e0 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 26 /*
231f0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 Database Name
23200 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
23210 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
23220 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 E_REINDEX
23230 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 27 /* I
23240 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e ndex Name N
23250 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
23260 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
23270 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 _ANALYZE
23280 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 28 /* Ta
23290 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
232a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
232b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
232c0 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 CREATE_VTABLE
232d0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 29 /* Tab
232e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 le Name Mod
232f0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a ule Name */.
23300 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
23310 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 ROP_VTABLE
23320 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 30 /* Tabl
23330 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 e Name Modu
23340 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 le Name */.#
23350 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 define SQLITE_FU
23360 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 NCTION
23370 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 31 /* NULL
23380 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 Funct
23390 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 ion Name */.#d
233a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 efine SQLITE_SAV
233b0 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 EPOINT
233c0 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 32 /* Operat
233d0 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f ion Savepo
233e0 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 int Name */.#de
233f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 fine SQLITE_COPY
23400 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
23410 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 0 /* No long
23420 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 er used */.#defi
23430 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 ne SQLITE_RECURS
23440 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33 IVE 3
23450 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 3 /* NULL
23460 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
23470 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a */../*.**
23480 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 CAPI3REF: Traci
23490 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 ng And Profiling
234a0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 Functions.** ME
234b0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
234c0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
234d0 65 73 20 61 72 65 20 64 65 70 72 65 63 61 74 65 es are deprecate
234e0 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 d. Use the [sqli
234f0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 te3_trace_v2()]
23500 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 interface.** ins
23510 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74 tead of the rout
23520 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 20 68 ines described h
23530 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ere..**.** These
23540 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 routines regist
23550 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
23560 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 tions that can b
23570 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 e used for.** tr
23580 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c acing and profil
23590 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f ing the executio
235a0 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 n of SQL stateme
235b0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
235c0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
235d0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 n registered by
235e0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
235f0 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a is invoked at.**
23600 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 various times w
23610 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 hen an SQL state
23620 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 ment is being ru
23630 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 n by [sqlite3_st
23640 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 ep()]..** ^The s
23650 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 qlite3_trace() c
23660 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
23670 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 ed with a UTF-8
23680 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
23690 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
236a0 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 t text as the st
236b0 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 atement first be
236c0 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a gins executing..
236d0 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 ** ^(Additional
236e0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
236f0 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 callbacks might
23700 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 occur.** as each
23710 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 triggered subpr
23720 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 ogram is entered
23730 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 . The callbacks
23740 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a for triggers.**
23750 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 contain a UTF-8
23760 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 SQL comment tha
23770 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 t identifies the
23780 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a trigger.)^.**.*
23790 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 * The [SQLITE_TR
237a0 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 ACE_SIZE_LIMIT]
237b0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
237c0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 ion can be used
237d0 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 to limit.** the
237e0 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 length of [bound
237f0 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 parameter] expa
23800 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 nsion in the out
23810 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 put of sqlite3_t
23820 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 race()..**.** ^T
23830 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
23840 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 tion registered
23850 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 by sqlite3_profi
23860 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a le() is invoked.
23870 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 ** as each SQL s
23880 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 tatement finishe
23890 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 s. ^The profile
238a0 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 callback contai
238b0 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e ns.** the origin
238c0 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 al statement tex
238d0 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 t and an estimat
238e0 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 e of wall-clock
238f0 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c time.** of how l
23900 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 ong that stateme
23910 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 nt took to run.
23920 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 ^The profile ca
23930 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 llback.** time i
23940 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 s in units of na
23950 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 noseconds, howev
23960 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 er the current i
23970 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a mplementation.**
23980 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 is only capable
23990 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 of millisecond
239a0 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 resolution so th
239b0 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e e six least sign
239c0 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 ificant.** digit
239d0 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 s in the time ar
239e0 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 e meaningless.
239f0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 Future versions
23a00 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 of SQLite.** mig
23a10 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 ht provide great
23a20 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e er resolution on
23a30 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 the profiler ca
23a40 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 llback. The.**
23a50 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 sqlite3_profile(
23a60 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f ) function is co
23a70 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d nsidered experim
23a80 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 ental and is.**
23a90 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
23aa0 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 e in future vers
23ab0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ions of SQLite..
23ac0 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 */.SQLITE_DEPREC
23ad0 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 ATED void *sqlit
23ae0 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 e3_trace(sqlite3
23af0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 *,. void(*xTra
23b00 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 ce)(void*,const
23b10 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a char*), void*);.
23b20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
23b30 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f D void *sqlite3_
23b40 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a profile(sqlite3*
23b50 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 ,. void(*xProf
23b60 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 ile)(void*,const
23b70 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 char*,sqlite3_u
23b80 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a int64), void*);.
23b90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
23ba0 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 SQL Trace Event
23bb0 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Codes.** KEYWOR
23bc0 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 DS: SQLITE_TRACE
23bd0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
23be0 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 stants identify
23bf0 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 classes of event
23c00 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f s that can be mo
23c10 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 nitored.** using
23c20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 the [sqlite3_tr
23c30 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e ace_v2()] tracin
23c40 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 4d 20 g logic. The M
23c50 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b argument.** to [
23c60 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 sqlite3_trace_v2
23c70 28 44 2c 4d 2c 58 2c 50 29 5d 20 69 73 20 61 6e (D,M,X,P)] is an
23c80 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 OR-ed combinati
23c90 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 on of one or mor
23ca0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c e of.** the foll
23cb0 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e owing constants.
23cc0 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 ^The first arg
23cd0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 ument to the tra
23ce0 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 ce callback.** i
23cf0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c s one of the fol
23d00 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 lowing constants
23d10 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 ..**.** New trac
23d20 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 ing constants ma
23d30 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
23d40 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a ture releases..*
23d50 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 *.** ^A trace ca
23d60 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20 llback has four
23d70 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c arguments: xCall
23d80 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a back(T,C,P,X)..*
23d90 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e * ^The T argumen
23da0 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 t is one of the
23db0 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64 integer type cod
23dc0 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 es above..** ^Th
23dd0 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 e C argument is
23de0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f a copy of the co
23df0 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 ntext pointer pa
23e00 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a ssed in as the.*
23e10 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e * fourth argumen
23e20 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 t to [sqlite3_tr
23e30 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 ace_v2()]..** Th
23e40 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 e P and X argume
23e50 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 nts are pointers
23e60 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 whose meanings
23e70 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a depend on T..**.
23e80 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c ** <dl>.** [[SQL
23e90 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d ITE_TRACE_STMT]]
23ea0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 <dt>SQLITE_TRAC
23eb0 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c E_STMT</dt>.** <
23ec0 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 dd>^An SQLITE_TR
23ed0 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 ACE_STMT callbac
23ee0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 k is invoked whe
23ef0 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 n a prepared sta
23f00 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 tement.** first
23f10 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 begins running a
23f20 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f nd possibly at o
23f30 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e ther times durin
23f40 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 g the.** executi
23f50 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 on of the prepar
23f60 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 ed statement, su
23f70 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61 ch as at the sta
23f80 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 rt of each.** tr
23f90 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d igger subprogram
23fa0 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e . ^The P argumen
23fb0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
23fc0 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 o the.** [prepar
23fd0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e ed statement]. ^
23fe0 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 The X argument i
23ff0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
24000 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a string which.**
24010 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64 is the unexpand
24020 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74 ed SQL text of t
24030 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
24040 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 ement or an SQL
24050 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 comment .** that
24060 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69 indicates the i
24070 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 nvocation of a t
24080 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61 rigger. ^The ca
24090 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 llback can compu
240a0 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 te.** the same t
240b0 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68 ext that would h
240c0 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 ave been returne
240d0 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20 d by the legacy
240e0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 [sqlite3_trace()
240f0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 ].** interface b
24100 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72 y using the X ar
24110 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65 gument when X be
24120 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61 gins with "--" a
24130 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b nd invoking.** [
24140 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 sqlite3_expanded
24150 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 _sql(P)] otherwi
24160 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 se..**.** [[SQLI
24170 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 TE_TRACE_PROFILE
24180 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 ]] <dt>SQLITE_TR
24190 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e ACE_PROFILE</dt>
241a0 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 .** <dd>^An SQLI
241b0 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 TE_TRACE_PROFILE
241c0 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 callback provid
241d0 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 es approximately
241e0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 the same.** inf
241f0 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70 ormation as is p
24200 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b rovided by the [
24210 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 sqlite3_profile(
24220 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 )] callback..**
24230 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 ^The P argument
24240 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
24250 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
24260 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 atement] and the
24270 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70 .** X argument p
24280 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69 oints to a 64-bi
24290 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 t integer which
242a0 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 is the estimated
242b0 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 of.** the numbe
242c0 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 r of nanosecond
242d0 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 that the prepare
242e0 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b d statement took
242f0 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 to run..** ^The
24300 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 SQLITE_TRACE_PR
24310 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 OFILE callback i
24320 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 s invoked when t
24330 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e he statement fin
24340 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 ishes..**.** [[S
24350 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d QLITE_TRACE_ROW]
24360 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 ] <dt>SQLITE_TRA
24370 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c CE_ROW</dt>.** <
24380 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 dd>^An SQLITE_TR
24390 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b ACE_ROW callback
243a0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e is invoked when
243b0 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a ever a prepared.
243c0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e ** statement gen
243d0 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20 erates a single
243e0 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 row of result.
243f0 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d .** ^The P argum
24400 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
24410 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 to the [prepare
24420 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 d statement] and
24430 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 the.** X argume
24440 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a nt is unused..**
24450 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 .** [[SQLITE_TRA
24460 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 CE_CLOSE]] <dt>S
24470 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 QLITE_TRACE_CLOS
24480 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 E</dt>.** <dd>^A
24490 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 n SQLITE_TRACE_C
244a0 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 LOSE callback is
244b0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 invoked when a
244c0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
244d0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a ection closes..*
244e0 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e * ^The P argumen
244f0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
24500 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 o the [database
24510 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 connection] obje
24520 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 ct.** and the X
24530 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 argument is unus
24540 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a ed..** </dl>.*/.
24550 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
24560 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20 RACE_STMT
24570 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 0x01.#define SQL
24580 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c ITE_TRACE_PROFIL
24590 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e E 0x02.#defin
245a0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 e SQLITE_TRACE_R
245b0 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23 OW 0x04.#
245c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 define SQLITE_TR
245d0 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 ACE_CLOSE 0
245e0 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 x08../*.** CAPI3
245f0 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48 REF: SQL Trace H
24600 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ook.** METHOD: s
24610 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
24620 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f e sqlite3_trace_
24630 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 v2(D,M,X,P) inte
24640 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 rface registers
24650 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b a trace callback
24660 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 .** function X a
24670 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65 gainst [database
24680 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 connection] D,
24690 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d using property m
246a0 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e ask M.** and con
246b0 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 text pointer P.
246c0 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62 ^If the X callb
246d0 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f ack is.** NULL o
246e0 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 r if the M mask
246f0 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 is zero, then tr
24700 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 acing is disable
24710 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 d. The.** M arg
24720 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 ument should be
24730 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65 the bitwise OR-e
24740 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 d combination of
24750 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 .** zero or more
24760 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 [SQLITE_TRACE]
24770 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a constants..**.**
24780 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 ^Each call to e
24790 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72 ither sqlite3_tr
247a0 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ace() or sqlite3
247b0 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72 _trace_v2() over
247c0 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 rides .** (cance
247d0 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61 ls) any prior ca
247e0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 lls to sqlite3_t
247f0 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 race() or sqlite
24800 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 3_trace_v2()..**
24810 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 .** ^The X callb
24820 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
24830 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74 henever any of t
24840 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 he events identi
24850 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b fied by .** mask
24860 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 M occur. ^The
24870 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76 integer return v
24880 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61 alue from the ca
24890 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e llback is curren
248a0 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 tly.** ignored,
248b0 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20 though this may
248c0 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 change in future
248d0 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c releases. Call
248e0 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e back.** implemen
248f0 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 tations should r
24900 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e eturn zero to en
24910 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70 sure future comp
24920 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a atibility..**.**
24930 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 ^A trace callba
24940 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 ck is invoked wi
24950 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 th four argument
24960 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c s: callback(T,C,
24970 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 P,X)..** ^The T
24980 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 argument is one
24990 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 of the [SQLITE_T
249a0 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e RACE].** constan
249b0 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 ts to indicate w
249c0 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 hy the callback
249d0 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 was invoked..**
249e0 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 ^The C argument
249f0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
24a00 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 context pointer
24a10 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 ..** The P and X
24a20 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 arguments are p
24a30 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 ointers whose me
24a40 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e anings depend on
24a50 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 T..**.** The sq
24a60 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 lite3_trace_v2()
24a70 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e interface is in
24a80 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63 tended to replac
24a90 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 e the legacy.**
24aa0 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 interfaces [sqli
24ab0 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 te3_trace()] and
24ac0 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c [sqlite3_profil
24ad0 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 e()], both of wh
24ae0 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 ich.** are depre
24af0 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 cated..*/.int sq
24b00 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a lite3_trace_v2(.
24b10 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e sqlite3*,. un
24b20 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 signed uMask,.
24b30 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 int(*xCallback)(
24b40 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 unsigned,void*,v
24b50 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 oid*,void*),. v
24b60 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a oid *pCtx.);../*
24b70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 .** CAPI3REF: Qu
24b80 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c ery Progress Cal
24b90 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 lbacks.** METHOD
24ba0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
24bb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f ^The sqlite3_pro
24bc0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c gress_handler(D,
24bd0 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 N,X,P) interface
24be0 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c causes the call
24bf0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e back.** function
24c00 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 X to be invoked
24c10 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 periodically du
24c20 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e ring long runnin
24c30 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 g calls to.** [s
24c40 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 qlite3_exec()],
24c50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
24c60 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 and [sqlite3_ge
24c70 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a t_table()] for.*
24c80 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
24c90 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 ction D. An exa
24ca0 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 mple use for thi
24cb0 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 s.** interface i
24cc0 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 s to keep a GUI
24cd0 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 updated during a
24ce0 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a large query..**
24cf0 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 .** ^The paramet
24d00 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 er P is passed t
24d10 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e hrough as the on
24d20 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ly parameter to
24d30 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b the .** callback
24d40 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 function X. ^T
24d50 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 he parameter N i
24d60 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 s the approximat
24d70 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 e number of .**
24d80 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 [virtual machine
24d90 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 instructions] t
24da0 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 hat are evaluate
24db0 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 d between succes
24dc0 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 sive.** invocati
24dd0 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 ons of the callb
24de0 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 ack X. ^If N is
24df0 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 less than one t
24e00 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 hen the progress
24e10 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 .** handler is d
24e20 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e isabled..**.** ^
24e30 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 Only a single pr
24e40 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d ogress handler m
24e50 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 ay be defined at
24e60 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a one time per.**
24e70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
24e80 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 ction]; setting
24e90 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 a new progress h
24ea0 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 andler cancels t
24eb0 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 he.** old one.
24ec0 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 ^Setting paramet
24ed0 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 er X to NULL dis
24ee0 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 ables the progre
24ef0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e ss handler..** ^
24f00 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e The progress han
24f10 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 dler is also dis
24f20 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 abled by setting
24f30 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 N to a value le
24f40 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a ss.** than 1..**
24f50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 .** ^If the prog
24f60 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 ress callback re
24f70 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
24f80 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 the operation is
24f90 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e .** interrupted.
24fa0 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 This feature c
24fb0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d an be used to im
24fc0 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 plement a.** "Ca
24fd0 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 ncel" button on
24fe0 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 a GUI progress d
24ff0 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a ialog box..**.**
25000 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 The progress ha
25010 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d ndler callback m
25020 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 ust not do anyth
25030 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f ing that will mo
25040 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 dify.** the data
25050 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
25060 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
25070 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
25080 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 r..** Note that
25090 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
250a0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 _v2()] and [sqli
250b0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 te3_step()] both
250c0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a modify their.**
250d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
250e0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 tions for the me
250f0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 aning of "modify
25100 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 " in this paragr
25110 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 aph..**.*/.void
25120 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 sqlite3_progress
25130 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
25140 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 *, int, int(*)(v
25150 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a oid*), void*);..
25160 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
25170 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 Opening A New Da
25180 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
25190 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 n.** CONSTRUCTOR
251a0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
251b0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
251c0 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 open an SQLite d
251d0 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 atabase file as
251e0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
251f0 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 .** filename ar
25200 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c gument. ^The fil
25210 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 ename argument i
25220 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
25230 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 UTF-8 for.** sq
25240 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 lite3_open() and
25250 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
25260 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 () and as UTF-16
25270 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 in the native b
25280 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 yte.** order for
25290 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
252a0 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 ). ^(A [database
252b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e connection] han
252c0 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a dle is usually.*
252d0 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 * returned in *p
252e0 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 pDb, even if an
252f0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 error occurs. T
25300 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f he only exceptio
25310 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 n is that.** if
25320 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 SQLite is unable
25330 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d to allocate mem
25340 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 ory to hold the
25350 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
25360 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c ,.** a NULL will
25370 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f be written into
25380 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f *ppDb instead o
25390 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 f a pointer to t
253a0 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 he [sqlite3].**
253b0 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 object.)^ ^(If t
253c0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
253d0 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 pened (and/or cr
253e0 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 eated) successfu
253f0 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 lly, then.** [SQ
25400 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 LITE_OK] is retu
25410 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 rned. Otherwise
25420 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
25430 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 is returned.)^
25440 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ^The.** [sqlite3
25450 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 _errmsg()] or [s
25460 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
25470 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 )] routines can
25480 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 be used to obtai
25490 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 n.** an English
254a0 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 language descrip
254b0 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f tion of the erro
254c0 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 r following a fa
254d0 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 ilure of any.**
254e0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f of the sqlite3_o
254f0 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a pen() routines..
25500 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 **.** ^The defau
25510 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c lt encoding will
25520 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 be UTF-8 for da
25530 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20 tabases created
25540 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 using.** sqlite3
25550 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 _open() or sqlit
25560 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e e3_open_v2(). ^
25570 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f The default enco
25580 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 ding for databas
25590 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 es.** created us
255a0 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ing sqlite3_open
255b0 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 16() will be UTF
255c0 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 -16 in the nativ
255d0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a e byte order..**
255e0 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e .** Whether or n
255f0 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 ot an error occu
25600 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 rs when it is op
25610 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a ened, resources.
25620 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
25630 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 th the [database
25640 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e connection] han
25650 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 dle should be re
25660 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 leased by.** pas
25670 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 sing it to [sqli
25680 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 te3_close()] whe
25690 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 n it is no longe
256a0 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a r required..**.*
256b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 * The sqlite3_op
256c0 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 en_v2() interfac
256d0 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c e works like sql
256e0 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 ite3_open().** e
256f0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 xcept that it ac
25700 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 cepts two additi
25710 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 onal parameters
25720 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 for additional c
25730 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 ontrol.** over t
25740 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 he new database
25750 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 connection. ^(T
25760 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 he flags paramet
25770 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 er to.** sqlite3
25780 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 _open_v2() can t
25790 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 ake one of.** th
257a0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 e following thre
257b0 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e e values, option
257c0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 ally combined wi
257d0 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 th the .** [SQLI
257e0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d TE_OPEN_NOMUTEX]
257f0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 , [SQLITE_OPEN_F
25800 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 ULLMUTEX], [SQLI
25810 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
25820 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 CHE],.** [SQLITE
25830 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 _OPEN_PRIVATECAC
25840 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c HE], and/or [SQL
25850 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c ITE_OPEN_URI] fl
25860 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c ags:)^.**.** <dl
25870 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 >.** ^(<dt>[SQLI
25880 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
25890 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 ]</dt>.** <dd>Th
258a0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
258b0 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c ened in read-onl
258c0 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 y mode. If the
258d0 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f database does no
258e0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 t.** already exi
258f0 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 st, an error is
25900 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e returned.</dd>)^
25910 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 .**.** ^(<dt>[SQ
25920 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
25930 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ITE]</dt>.** <dd
25940 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 >The database is
25950 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 opened for read
25960 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 ing and writing
25970 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 if possible, or
25980 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 reading.** only
25990 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 if the file is w
259a0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 rite protected b
259b0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 y the operating
259c0 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 system. In eith
259d0 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 er.** case the d
259e0 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 atabase must alr
259f0 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 eady exist, othe
25a00 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 rwise an error i
25a10 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e s returned.</dd>
25a20 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b )^.**.** ^(<dt>[
25a30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
25a40 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 WRITE] | [SQLITE
25a50 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 _OPEN_CREATE]</d
25a60 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 t>.** <dd>The da
25a70 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
25a80 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 for reading and
25a90 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 writing, and is
25aa0 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 created if.** i
25ab0 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 t does not alrea
25ac0 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 dy exist. This i
25ad0 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 s the behavior t
25ae0 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 hat is always us
25af0 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 ed for.** sqlite
25b00 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 3_open() and sql
25b10 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f ite3_open16().</
25b20 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a dd>)^.** </dl>.*
25b30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 *.** If the 3rd
25b40 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
25b50 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
25b60 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 s not one of the
25b70 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 .** combinations
25b80 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 shown above opt
25b90 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 ionally combined
25ba0 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b with other.** [
25bb0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
25bc0 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 ONLY | SQLITE_OP
25bd0 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 EN_* bits].** th
25be0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
25bf0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
25c00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c .** ^If the [SQL
25c10 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
25c20 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 ] flag is set, t
25c30 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
25c40 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f connection.** o
25c50 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 pens in the mult
25c60 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 i-thread [thread
25c70 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e ing mode] as lon
25c80 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d g as the single-
25c90 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 thread.** mode h
25ca0 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 as not been set
25cb0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 at compile-time
25cc0 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 or start-time.
25cd0 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ^If the.** [SQLI
25ce0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 TE_OPEN_FULLMUTE
25cf0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 X] flag is set t
25d00 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
25d10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e connection open
25d20 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 s.** in the seri
25d30 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
25d40 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 g mode] unless s
25d50 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 ingle-thread was
25d60 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 .** previously s
25d70 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 elected at compi
25d80 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 le-time or start
25d90 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b -time..** ^The [
25da0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
25db0 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 EDCACHE] flag ca
25dc0 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 uses the databas
25dd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 e connection to
25de0 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 be.** eligible t
25df0 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 o use [shared ca
25e00 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 che mode], regar
25e10 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 dless of whether
25e20 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a or not shared.*
25e30 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c * cache is enabl
25e40 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
25e50 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 3_enable_shared_
25e60 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a cache()]. ^The.
25e70 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
25e80 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c PRIVATECACHE] fl
25e90 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 ag causes the da
25ea0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
25eb0 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 n to not.** part
25ec0 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 icipate in [shar
25ed0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 ed cache mode] e
25ee0 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 ven if it is ena
25ef0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 bled..**.** ^The
25f00 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
25f10 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
25f20 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 n_v2() is the na
25f30 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 me of the.** [sq
25f40 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
25f50 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 t that defines t
25f60 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
25f70 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 tem interface th
25f80 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 at.** the new da
25f90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
25fa0 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e n should use. ^
25fb0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
25fc0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 rameter is.** a
25fd0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
25fe0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 n the default [s
25ff0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
26000 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a ct is used..**.*
26010 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 * ^If the filena
26020 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 me is ":memory:"
26030 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 , then a private
26040 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d , temporary in-m
26050 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a emory database.*
26060 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 * is created for
26070 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e the connection.
26080 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 ^This in-memor
26090 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 y database will
260a0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 vanish when.** t
260b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
260c0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 ection is closed
260d0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
260e0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 ns of SQLite mig
260f0 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f ht.** make use o
26100 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 f additional spe
26110 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 cial filenames t
26120 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 hat begin with t
26130 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 he ":" character
26140 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d ..** It is recom
26150 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e mended that when
26160 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
26170 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f name actually do
26180 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a es begin with.**
26190 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 a ":" character
261a0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 you should pref
261b0 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 ix the filename
261c0 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 with a pathname
261d0 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 such as.** "./"
261e0 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 to avoid ambigui
261f0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ty..**.** ^If th
26200 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e e filename is an
26210 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 empty string, t
26220 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 hen a private, t
26230 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 emporary.** on-d
26240 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c isk database wil
26250 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e l be created. ^
26260 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 This private dat
26270 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a abase will be.**
26280 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 automatically d
26290 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 eleted as soon a
262a0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 s the database c
262b0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f onnection is clo
262c0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 sed..**.** [[URI
262d0 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 filenames in sq
262e0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c lite3_open()]] <
262f0 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 h3>URI Filenames
26300 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 </h3>.**.** ^If
26310 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 [URI filename] i
26320 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 nterpretation is
26330 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 enabled, and th
26340 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d e filename argum
26350 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 ent.** begins wi
26360 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e th "file:", then
26370 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 the filename is
26380 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
26390 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 a URI. ^URI.** f
263a0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 ilename interpre
263b0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 tation is enable
263c0 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 d if the [SQLITE
263d0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 _OPEN_URI] flag
263e0 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 is.** set in the
263f0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
26400 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
26410 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 v2(), or if it h
26420 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c as.** been enabl
26430 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e ed globally usin
26440 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f g the [SQLITE_CO
26450 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e NFIG_URI] option
26460 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 with the.** [sq
26470 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
26480 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 method or by the
26490 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 [SQLITE_USE_URI
264a0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
264b0 70 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69 ption..** URI fi
264c0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 lename interpret
264d0 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 ation is turned
264e0 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c off.** by defaul
264f0 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 t, but future re
26500 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
26510 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 might enable UR
26520 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e I filename.** in
26530 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 terpretation by
26540 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b default. See "[
26550 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 URI filenames]"
26560 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
26570 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
26580 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d *.** URI filenam
26590 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 es are parsed ac
265a0 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 cording to RFC 3
265b0 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 986. ^If the URI
265c0 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 contains an.**
265d0 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 authority, then
265e0 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 it must be eithe
265f0 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e r an empty strin
26600 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 g or the string
26610 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e .** "localhost".
26620 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 ^If the authori
26630 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 ty is not an emp
26640 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f ty string or "lo
26650 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a calhost", an .**
26660 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
26670 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 ed to the caller
26680 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 . ^The fragment
26690 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 component of a U
266a0 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 RI, if .** prese
266b0 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a nt, is ignored..
266c0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 **.** ^SQLite us
266d0 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 es the path comp
266e0 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 onent of the URI
266f0 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 as the name of
26700 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a the disk file.**
26710 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 which contains
26720 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 the database. ^I
26730 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e f the path begin
26740 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 s with a '/' cha
26750 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e racter, .** then
26760 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 it is interpret
26770 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 ed as an absolut
26780 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 e path. ^If the
26790 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 path does not be
267a0 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 gin .** with a '
267b0 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 /' (meaning that
267c0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 the authority s
267d0 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 ection is omitte
267e0 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a d from the URI).
267f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 ** then the path
26800 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
26810 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 as a relative pa
26820 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e th. .** ^(On win
26830 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 dows, the first
26840 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 component of an
26850 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a absolute path .*
26860 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 * is a drive spe
26870 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e cification (e.g.
26880 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 "C:").)^.**.**
26890 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 [[core URI query
268a0 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a parameters]].**
268b0 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f The query compo
268c0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 nent of a URI ma
268d0 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 y contain parame
268e0 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e ters that are in
268f0 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 terpreted.** eit
26900 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 her by SQLite it
26910 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 self, or by a [V
26920 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 FS | custom VFS
26930 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e implementation].
26940 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 .** SQLite and i
26950 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 ts built-in [VFS
26960 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 es] interpret th
26970 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 e.** following q
26980 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a uery parameters:
26990 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 .**.** <ul>.**
269a0 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e <li> <b>vfs</b>
269b0 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 : ^The "vfs" par
269c0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 ameter may be us
269d0 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 ed to specify th
269e0 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 e name of.**
269f0 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 a VFS object th
26a00 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 at provides the
26a10 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
26a20 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 interface that
26a30 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 should.** be
26a40 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 used to access
26a50 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
26a60 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 e on disk. ^If t
26a70 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 his option is se
26a80 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 t to.** an e
26a90 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 mpty string the
26aa0 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 default VFS obje
26ab0 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 ct is used. ^Spe
26ac0 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f cifying an unkno
26ad0 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 wn.** VFS is
26ae0 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 an error. ^If s
26af0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
26b00 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 is used and the
26b10 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a vfs option is.*
26b20 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 * present, t
26b30 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 hen the VFS spec
26b40 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 ified by the opt
26b50 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 ion takes preced
26b60 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 ence over.**
26b70 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 the value passe
26b80 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 d as the fourth
26b90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
26ba0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a ite3_open_v2()..
26bb0 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e **.** <li> <b>
26bc0 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 mode</b>: ^(The
26bd0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d mode parameter m
26be0 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 ay be set to eit
26bf0 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a her "ro", "rw",.
26c00 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 ** "rwc", or
26c10 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d "memory". Attem
26c20 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 pting to set it
26c30 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c to any other val
26c40 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 ue is.** an
26c50 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 error)^. .**
26c60 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 ^If "ro" is spe
26c70 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 cified, then the
26c80 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
26c90 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c ned for read-onl
26ca0 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 y .** access
26cb0 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 , just as if the
26cc0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
26cd0 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 ADONLY] flag had
26ce0 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 been set in the
26cf0 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 .** third a
26d00 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
26d10 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 e3_open_v2(). ^I
26d20 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f f the mode optio
26d30 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 n is set to .**
26d40 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 "rw", then 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 66 6f 72 20 72 65 61 64 2d 77 pened for read-w
26d70 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 rite (but not cr
26d80 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 eate) .** ac
26d90 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 cess, as if SQLI
26da0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
26db0 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 E (but not SQLIT
26dc0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 E_OPEN_CREATE) h
26dd0 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 ad .** been
26de0 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 set. ^Value "rwc
26df0 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 " is equivalent
26e00 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 to setting both
26e10 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f .** SQLITE_O
26e20 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e PEN_READWRITE an
26e30 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 d SQLITE_OPEN_CR
26e40 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d EATE. ^If the m
26e50 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a ode option is.**
26e60 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d set to "mem
26e70 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 ory" then a pure
26e80 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 [in-memory data
26e90 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 base] that never
26ea0 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 reads.** or
26eb0 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 writes from dis
26ec0 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 k is used. ^It i
26ed0 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 s an error to sp
26ee0 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f ecify a value fo
26ef0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 r.** the mod
26f00 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 e parameter that
26f10 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 is less restric
26f20 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 tive than that s
26f30 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 pecified by.**
26f40 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 the flags pas
26f50 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 sed in the third
26f60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
26f70 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
26f80 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 .**.** <li> <b
26f90 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 >cache</b>: ^The
26fa0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 cache parameter
26fb0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 may be set to e
26fc0 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f ither "shared" o
26fd0 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 r.** "privat
26fe0 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 e". ^Setting it
26ff0 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 to "shared" is e
27000 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 quivalent to set
27010 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 ting the.**
27020 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
27030 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 EDCACHE bit in t
27040 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
27050 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 t passed to.**
27060 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f sqlite3_open_
27070 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 v2(). ^Setting t
27080 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 he cache paramet
27090 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 er to "private"
270a0 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 is .** equiv
270b0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 alent to setting
270c0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e the SQLITE_OPEN
270d0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 _PRIVATECACHE bi
270e0 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 t..** ^If sq
270f0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
27100 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 is used and the
27110 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 "cache" paramete
27120 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a r is present in.
27130 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c ** a URI fil
27140 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 ename, its value
27150 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 overrides any b
27160 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 ehavior requeste
27170 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 d by setting.**
27180 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f SQLITE_OPEN_
27190 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 PRIVATECACHE or
271a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
271b0 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a EDCACHE flag..**
271c0 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f .** <li> <b>pso
271d0 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 w</b>: ^The psow
271e0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 parameter indic
271f0 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 ates whether or
27200 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b not the.** [
27210 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 powersafe overwr
27220 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f ite] property do
27230 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 es or does not a
27240 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 pply to the.**
27250 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 storage media
27260 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 on which the da
27270 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 tabase file resi
27280 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e des..**.** <li>
27290 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 <b>nolock</b>:
272a0 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 ^The nolock para
272b0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 meter is a boole
272c0 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 an query paramet
272d0 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 er.** which
272e0 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 if set disables
272f0 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 file locking in
27300 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c rollback journal
27310 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a modes. This.**
27320 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 is useful f
27330 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 or accessing a d
27340 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c atabase on a fil
27350 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 esystem that doe
27360 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 s not.** sup
27370 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 port locking. C
27380 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 aution: Databas
27390 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 e corruption mig
273a0 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f ht result if two
273b0 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 .** or more
273c0 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 processes write
273d0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 to the same data
273e0 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 base and any one
273f0 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 of those.**
27400 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 processes uses
27410 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 nolock=1..**.**
27420 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 <li> <b>immutab
27430 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d le</b>: ^The imm
27440 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 utable parameter
27450 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 is a boolean qu
27460 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d ery.** param
27470 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 eter that indica
27480 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 tes that the dat
27490 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 abase file is st
274a0 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 ored on.** r
274b0 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 ead-only media.
274c0 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 ^When immutable
274d0 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 is set, SQLite
274e0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 assumes that the
274f0 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 .** database
27500 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 file cannot be
27510 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 changed, even by
27520 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 a process with
27530 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 higher.** pr
27540 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 ivilege, and so
27550 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
27560 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 opened read-only
27570 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 and all locking
27580 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e .** and chan
27590 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 ge detection is
275a0 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 disabled. Cauti
275b0 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 on: Setting the
275c0 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 immutable.**
275d0 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 property on a d
275e0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 atabase file tha
275f0 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 t does in fact c
27600 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 hange can result
27610 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 .** in incor
27620 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c rect query resul
27630 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 ts and/or [SQLIT
27640 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 E_CORRUPT] error
27650 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c s..** See al
27660 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 so: [SQLITE_IOCA
27670 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a P_IMMUTABLE]..**
27680 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e .** </ul>
27690 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 .**.** ^Specifyi
276a0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 ng an unknown pa
276b0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 rameter in the q
276c0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f uery component o
276d0 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 f a URI is not a
276e0 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 n.** error. Fut
276f0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
27700 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 SQLite might und
27710 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e erstand addition
27720 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 al query.** para
27730 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 meters. See "[q
27740 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 uery parameters
27750 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 with special mea
27760 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 ning to SQLite]"
27770 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e for.** addition
27780 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
27790 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 **.** [[URI file
277a0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 name examples]]
277b0 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 <h3>URI filename
277c0 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a examples</h3>.*
277d0 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 *.** <table bord
277e0 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e er="1" align=cen
277f0 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d ter cellpadding=
27800 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 5>.** <tr><th> U
27810 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 RI filenames <th
27820 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 > Results.** <tr
27830 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e ><td> file:data.
27840 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 db <td> .**
27850 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 Open the fi
27860 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 le "data.db" in
27870 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 the current dire
27880 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 ctory..** <tr><t
27890 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 d> file:/home/fr
278a0 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a ed/data.db<br>.*
278b0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a * file:
278c0 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 ///home/fred/dat
278d0 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 a.db <br> .**
278e0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f file://lo
278f0 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 calhost/home/fre
27900 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c d/data.db <br> <
27910 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 td> .**
27920 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 Open the databa
27930 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 se file "/home/f
27940 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a red/data.db"..**
27950 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f <tr><td> file:/
27960 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 /darkstar/home/f
27970 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e red/data.db <td>
27980 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e .** An
27990 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 error. "darksta
279a0 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f r" is not a reco
279b0 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 gnized authority
279c0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 ..** <tr><td sty
279d0 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a le="white-space:
279e0 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 nowrap"> .**
279f0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a file:///C:
27a00 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 /Documents%20and
27a10 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 %20Settings/fred
27a20 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 /Desktop/data.db
27a30 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e .** <td> Win
27a40 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 dows only: Open
27a50 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 the file "data.d
27a60 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 b" on fred's des
27a70 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a ktop on drive.**
27a80 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f C:. No
27a90 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 te that the %20
27aa0 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 escaping in this
27ab0 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 example is not
27ac0 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 strictly .**
27ad0 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 necessary
27ae0 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 - space characte
27af0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c rs can be used l
27b00 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 iterally.**
27b10 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 in URI file
27b20 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 names..** <tr><t
27b30 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f d> file:data.db?
27b40 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 mode=ro&cache=pr
27b50 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 ivate <td> .**
27b60 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c Open fil
27b70 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 e "data.db" in t
27b80 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 he current direc
27b90 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e tory for read-on
27ba0 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 ly access..**
27bb0 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 Regardles
27bc0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
27bd0 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 not shared-cache
27be0 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 mode is enabled
27bf0 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 by.**
27c00 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 default, use a p
27c10 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a rivate cache..**
27c20 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f <tr><td> file:/
27c30 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
27c40 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 b?vfs=unix-dotfi
27c50 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 le <td>.**
27c60 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f Open file "/
27c70 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
27c80 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 b". Use the spec
27c90 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f ial VFS "unix-do
27ca0 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 tfile".**
27cb0 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 that uses dot
27cc0 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 -files in place
27cd0 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 of posix advisor
27ce0 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 y locking..** <t
27cf0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 r><td> file:data
27d00 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c .db?mode=readonl
27d10 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 y <td> .**
27d20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 An error. "r
27d30 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 eadonly" is not
27d40 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 a valid option f
27d50 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 or the "mode" pa
27d60 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 rameter..** </ta
27d70 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 ble>.**.** ^URI
27d80 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 hexadecimal esca
27d90 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 pe sequences (%H
27da0 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 H) are supported
27db0 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 within the path
27dc0 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f and.** query co
27dd0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 mponents of a UR
27de0 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c I. A hexadecimal
27df0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 escape sequence
27e00 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a consists of a.*
27e10 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d * percent sign -
27e20 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 "%" - followed
27e30 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 by exactly two h
27e40 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 exadecimal digit
27e50 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 s .** specifying
27e60 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e an octet value.
27e70 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 ^Before the pat
27e80 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f h or query compo
27e90 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 nents of a.** UR
27ea0 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 I filename are i
27eb0 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 nterpreted, they
27ec0 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 are encoded usi
27ed0 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c ng UTF-8 and all
27ee0 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c .** hexadecimal
27ef0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 escape sequence
27f00 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 s replaced by a
27f10 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 single byte cont
27f20 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f aining the.** co
27f30 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 rresponding octe
27f40 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 t. If this proce
27f50 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 ss generates an
27f60 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e invalid UTF-8 en
27f70 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 coding,.** the r
27f80 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 esults are undef
27f90 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e ined..**.** <b>N
27fa0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 ote to Windows u
27fb0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 sers:</b> The e
27fc0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 ncoding used for
27fd0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 the filename ar
27fe0 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c gument.** of sql
27ff0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
28000 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
28010 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c ) must be UTF-8,
28020 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a not whatever.**
28030 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 codepage is cur
28040 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 rently defined.
28050 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 Filenames conta
28060 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f ining internatio
28070 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 nal.** character
28080 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 s must be conver
28090 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 ted to UTF-8 pri
280a0 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 or to passing th
280b0 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 em into.** sqlit
280c0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c e3_open() or sql
280d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a ite3_open_v2()..
280e0 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f **.** <b>Note to
280f0 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 Windows Runtime
28100 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 users:</b> The
28110 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 temporary direc
28120 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 tory must be set
28130 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c .** prior to cal
28140 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 ling sqlite3_ope
28150 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f n() or sqlite3_o
28160 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 pen_v2(). Other
28170 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a wise, various.**
28180 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 features that r
28190 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f equire the use o
281a0 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 f temporary file
281b0 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a s may fail..**.*
281c0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
281d0 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 ite3_temp_direct
281e0 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ory].*/.int sqli
281f0 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 te3_open(. cons
28200 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
28210 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
28220 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
28230 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
28240 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a ppDb /*
28250 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
28260 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 handle */.);.int
28270 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
28280 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 . const void *f
28290 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 ilename, /* Da
282a0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
282b0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 (UTF-16) */. sq
282c0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 lite3 **ppDb
282d0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 /* OUT: SQ
282e0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a Lite db handle *
282f0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 /.);.int sqlite3
28300 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 _open_v2(. cons
28310 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
28320 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
28330 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
28340 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
28350 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a ppDb, /*
28360 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
28370 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 handle */. int
28380 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 flags,
28390 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a /* Flags */.
283a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 const char *zV
283b0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d fs /* Nam
283c0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 e of VFS module
283d0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a to use */.);../*
283e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
283f0 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 tain Values For
28400 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a URI Parameters.*
28410 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 *.** These are u
28420 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c tility routines,
28430 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 useful to VFS i
28440 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 mplementations,
28450 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f that check.** to
28460 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 see if a databa
28470 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 se file was a UR
28480 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 I that contained
28490 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 a specific quer
284a0 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c y .** parameter,
284b0 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 and if so obtai
284c0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 ns the value of
284d0 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d that query param
284e0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 eter..**.** If F
284f0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 is the database
28500 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 filename pointe
28510 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 r passed into th
28520 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 e xOpen() method
28530 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d of .** a VFS im
28540 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 plementation whe
28550 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 n the flags para
28560 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 meter to xOpen()
28570 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 has one or .**
28580 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c more of the [SQL
28590 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 ITE_OPEN_URI] or
285a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
285b0 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 IN_DB] bits set
285c0 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 and.** P is the
285d0 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 name of the quer
285e0 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 y parameter, the
285f0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 n.** sqlite3_uri
28600 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 _parameter(F,P)
28610 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 returns the valu
28620 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 e of the P.** pa
28630 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 rameter if it ex
28640 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 ists or a NULL p
28650 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 ointer if P does
28660 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 not appear as a
28670 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d .** query param
28680 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 eter on F. If P
28690 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 is a query para
286a0 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 meter of F.** ha
286b0 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 s no explicit va
286c0 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 lue, then sqlite
286d0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 3_uri_parameter(
286e0 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 F,P) returns.**
286f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
28700 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a empty string..**
28710 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
28720 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
28730 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d B) routine assum
28740 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 es that P is a b
28750 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 oolean.** parame
28760 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ter and returns
28770 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 true (1) or fals
28780 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 e (0) according
28790 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 to the value.**
287a0 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 of P. The sqlit
287b0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
287c0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 ,P,B) routine re
287d0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 turns true (1) i
287e0 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f f the.** value o
287f0 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 f query paramete
28800 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 r P is one of "y
28810 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 es", "true", or
28820 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 "on" in any.** c
28830 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 ase or if the va
28840 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 lue begins with
28850 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 a non-zero numbe
28860 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 r. The .** sqli
28870 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
28880 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 F,P,B) routines
28890 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 returns false (0
288a0 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f ) if the value o
288b0 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d f.** query param
288c0 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 eter P is one of
288d0 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 "no", "false",
288e0 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 or "off" in any
288f0 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 case or.** if th
28900 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 e value begins w
28910 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 ith a numeric ze
28920 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 ro. If P is not
28930 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 a query.** para
28940 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 meter on F or if
28950 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
28960 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 is does not matc
28970 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 h any of the.**
28980 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 above, then sqli
28990 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
289a0 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 F,P,B) returns (
289b0 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 B!=0)..**.** The
289c0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 sqlite3_uri_int
289d0 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 64(F,P,D) routin
289e0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 e converts the v
289f0 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 alue of P into a
28a00 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 .** 64-bit signe
28a10 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 d integer and re
28a20 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 turns that integ
28a30 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f er, or D if P do
28a40 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e es not.** exist.
28a50 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f If the value o
28a60 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 f P is something
28a70 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 other than an i
28a80 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 nteger, then.**
28a90 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 zero is returned
28aa0 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 ..** .** If F is
28ab0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
28ac0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 then sqlite3_ur
28ad0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 i_parameter(F,P)
28ae0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e returns NULL an
28af0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 d.** sqlite3_uri
28b00 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
28b10 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 returns B. If F
28b20 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 is not a NULL p
28b30 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 ointer and.** is
28b40 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 not a database
28b50 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f file pathname po
28b60 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 inter that SQLit
28b70 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 e passed into th
28b80 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d e xOpen.** VFS m
28b90 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 ethod, then the
28ba0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 behavior of this
28bb0 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 routine is unde
28bc0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
28bd0 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c ly.** undesirabl
28be0 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 e..*/.const char
28bf0 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 *sqlite3_uri_pa
28c00 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 rameter(const ch
28c10 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 ar *zFilename, c
28c20 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 onst char *zPara
28c30 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f m);.int sqlite3_
28c40 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 uri_boolean(cons
28c50 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 t char *zFile, c
28c60 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 onst char *zPara
28c70 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 m, int bDefault)
28c80 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 ;.sqlite3_int64
28c90 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 sqlite3_uri_int6
28ca0 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 4(const char*, c
28cb0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 onst char*, sqli
28cc0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a te3_int64);.../*
28cd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 .** CAPI3REF: Er
28ce0 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 ror Codes And Me
28cf0 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 ssages.** METHOD
28d00 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
28d10 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ^If the most rec
28d20 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 ent sqlite3_* AP
28d30 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 I call associate
28d40 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 d with .** [data
28d50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
28d60 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 D failed, then
28d70 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 the sqlite3_errc
28d80 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 ode(D) interface
28d90 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 .** returns the
28da0 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 numeric [result
28db0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 code] or [extend
28dc0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 ed result code]
28dd0 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 for that.** API
28de0 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 call..** If the
28df0 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 most recent API
28e00 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 call was success
28e10 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ful,.** then the
28e20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 return value fr
28e30 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f om sqlite3_errco
28e40 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 de() is undefine
28e50 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 d..** ^The sqlit
28e60 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 e3_extended_errc
28e70 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 ode().** interfa
28e80 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 ce is the same e
28e90 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c xcept that it al
28ea0 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 ways returns the
28eb0 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 .** [extended r
28ec0 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e esult code] even
28ed0 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 when extended r
28ee0 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a esult codes are.
28ef0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a ** disabled..**.
28f00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
28f10 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c errmsg() and sql
28f20 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 ite3_errmsg16()
28f30 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c return English-l
28f40 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 anguage.** text
28f50 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 that describes t
28f60 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 he error, as eit
28f70 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 her UTF-8 or UTF
28f80 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 -16 respectively
28f90 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f ..** ^(Memory to
28fa0 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 hold the error
28fb0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 message string i
28fc0 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e s managed intern
28fd0 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 ally..** The app
28fe0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f lication does no
28ff0 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 t need to worry
29000 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 about freeing th
29010 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 e result..** How
29020 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 ever, the error
29030 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 string might be
29040 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 overwritten or d
29050 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a eallocated by.**
29060 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
29070 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 s to other SQLit
29080 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 e interface func
29090 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e tions.)^.**.** ^
290a0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 The sqlite3_errs
290b0 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 tr() interface r
290c0 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 eturns the Engli
290d0 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 sh-language text
290e0 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 .** that describ
290f0 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 es the [result c
29100 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a ode], as UTF-8..
29110 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 ** ^(Memory to h
29120 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 old the error me
29130 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 ssage string is
29140 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c managed internal
29150 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e ly.** and must n
29160 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 ot be freed by t
29170 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e he application)^
29180 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
29190 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 serialized [thr
291a0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 eading mode] is
291b0 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 in use, it might
291c0 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 be the.** case
291d0 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 that a second er
291e0 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 ror occurs on a
291f0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 separate thread
29200 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 in between.** th
29210 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 e time of the fi
29220 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 rst error and th
29230 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 e call to these
29240 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 interfaces..** W
29250 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 hen that happens
29260 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 , the second err
29270 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 or will be repor
29280 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a ted since these.
29290 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c ** interfaces al
292a0 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 ways report the
292b0 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 most recent resu
292c0 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a lt. To avoid.**
292d0 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 this, each thre
292e0 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 ad can obtain ex
292f0 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 clusive use of t
29300 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
29310 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 nection] D.** by
29320 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 invoking [sqlit
29330 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 e3_mutex_enter](
29340 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 [sqlite3_db_mute
29350 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 x](D)) before be
29360 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 ginning.** to us
29370 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 e D and invoking
29380 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
29390 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f leave]([sqlite3_
293a0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 db_mutex](D)) af
293b0 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 ter.** all calls
293c0 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 to the interfac
293d0 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 es listed here a
293e0 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a re completed..**
293f0 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 .** If an interf
29400 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 ace fails with S
29410 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 QLITE_MISUSE, th
29420 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 at means the int
29430 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e erface.** was in
29440 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c voked incorrectl
29450 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 y by the applica
29460 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 tion. In that c
29470 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f ase, the.** erro
29480 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 r code and messa
29490 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f ge may or may no
294a0 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 t be set..*/.int
294b0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
294c0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 (sqlite3 *db);.i
294d0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e nt sqlite3_exten
294e0 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 ded_errcode(sqli
294f0 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 te3 *db);.const
29500 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 char *sqlite3_er
29510 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a rmsg(sqlite3*);.
29520 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
29530 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c te3_errmsg16(sql
29540 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 ite3*);.const ch
29550 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 ar *sqlite3_errs
29560 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 tr(int);../*.**
29570 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 CAPI3REF: Prepar
29580 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a ed Statement Obj
29590 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ect.** KEYWORDS:
295a0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
295b0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 ment} {prepared
295c0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a statements}.**.*
295d0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
295e0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 this object rep
295f0 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 resents a single
29600 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
29610 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 hat.** has been
29620 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 compiled into bi
29630 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 nary form and is
29640 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 ready to be eva
29650 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 luated..**.** Th
29660 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 ink of each SQL
29670 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 statement as a s
29680 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 eparate computer
29690 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a program. The.*
296a0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 * original SQL t
296b0 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f ext is source co
296c0 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 de. A prepared
296d0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 statement object
296e0 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 .** is the comp
296f0 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 iled object code
29700 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 . All SQL must
29710 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 be converted int
29720 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 o a.** prepared
29730 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 statement before
29740 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a it can be run..
29750 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 **.** The life-c
29760 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 ycle of a prepar
29770 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a ed statement obj
29780 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 ect usually goes
29790 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a like this:.**.*
297a0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 * <ol>.** <li> C
297b0 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72 reate the prepar
297c0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a ed statement obj
297d0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ect using [sqlit
297e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
297f0 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 ..** <li> Bind v
29800 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 alues to [parame
29810 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 ters] using the
29820 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
29830 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 .** interfa
29840 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e ces..** <li> Run
29850 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c the SQL by call
29860 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
29870 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 p()] one or more
29880 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 times..** <li>
29890 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 Reset the prepar
298a0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 ed statement usi
298b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
298c0 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 t()] then go bac
298d0 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 k.** to ste
298e0 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 p 2. Do this ze
298f0 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ro or more times
29900 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f ..** <li> Destro
29910 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 y the object usi
29920 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
29930 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c lize()]..** </ol
29940 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 >.*/.typedef str
29950 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 uct sqlite3_stmt
29960 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a sqlite3_stmt;..
29970 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
29980 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a Run-time Limits.
29990 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
299a0 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 e3.**.** ^(This
299b0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 interface allows
299c0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 the size of var
299d0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 ious constructs
299e0 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a to be limited.**
299f0 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e on a connection
29a00 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 by connection b
29a10 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 asis. The first
29a20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
29a30 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
29a40 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 onnection] whose
29a50 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 limit is to be
29a60 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 set or queried.
29a70 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 The.** second p
29a80 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 arameter is one
29a90 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 of the [limit ca
29aa0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 tegories] that d
29ab0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 efine a.** class
29ac0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 of constructs t
29ad0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 o be size limite
29ae0 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 d. The third pa
29af0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
29b00 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 * new limit for
29b10 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 that construct.)
29b20 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ^.**.** ^If the
29b30 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e new limit is a n
29b40 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 egative number,
29b50 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 the limit is unc
29b60 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 hanged..** ^(For
29b70 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 each limit cate
29b80 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 gory SQLITE_LIMI
29b90 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 T_<i>NAME</i> th
29ba0 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 ere is a .** [li
29bb0 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 mits | hard uppe
29bc0 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 r bound].** set
29bd0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 at compile-time
29be0 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 by a C preproces
29bf0 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 sor macro called
29c00 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 .** [limits | SQ
29c10 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 LITE_MAX_<i>NAME
29c20 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 </i>]..** (The "
29c30 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 _LIMIT_" in the
29c40 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 name is changed
29c50 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a to "_MAX_".))^.*
29c60 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 * ^Attempts to i
29c70 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 ncrease a limit
29c80 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 above its hard u
29c90 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a pper bound are.*
29ca0 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 * silently trunc
29cb0 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 ated to the hard
29cc0 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a upper bound..**
29cd0 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 .** ^Regardless
29ce0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
29cf0 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 t the limit was
29d00 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a changed, the .**
29d10 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
29d20 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
29d30 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 urns the prior v
29d40 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 alue of the limi
29d50 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f t..** ^Hence, to
29d60 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e find the curren
29d70 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d t value of a lim
29d80 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 it without chang
29d90 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c ing it,.** simpl
29da0 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e y invoke this in
29db0 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 terface with the
29dc0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
29dd0 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a set to -1..**.*
29de0 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 * Run-time limit
29df0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 s are intended f
29e00 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 or use in applic
29e10 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 ations that mana
29e20 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 ge.** both their
29e30 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 own internal da
29e40 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 tabase and also
29e50 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 databases that a
29e60 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a re controlled.**
29e70 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 by untrusted ex
29e80 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 ternal sources.
29e90 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c An example appl
29ea0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 ication might be
29eb0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 a.** web browse
29ec0 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f r that has its o
29ed0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 wn databases for
29ee0 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 storing history
29ef0 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 and.** separate
29f00 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 databases contr
29f10 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 olled by JavaScr
29f20 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 ipt applications
29f30 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f downloaded.** o
29f40 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e ff the Internet.
29f50 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 The internal d
29f60 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 atabases can be
29f70 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 given the.** lar
29f80 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 ge, default limi
29f90 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d ts. Databases m
29fa0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e anaged by extern
29fb0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a al sources can.*
29fc0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 * be given much
29fd0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 smaller limits d
29fe0 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 esigned to preve
29ff0 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 nt a denial of s
2a000 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b ervice.** attack
2a010 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 . Developers mi
2a020 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f ght also want to
2a030 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 use the [sqlite
2a040 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
2a050 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
2a060 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 to further cont
2a070 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 rol untrusted SQ
2a080 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 L. The size of
2a090 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
2a0a0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e created by an un
2a0b0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 trusted script c
2a0c0 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 an be contained
2a0d0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 using the.** [ma
2a0e0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 x_page_count] [P
2a0f0 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 RAGMA]..**.** Ne
2a100 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 w run-time limit
2a110 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 categories may
2a120 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
2a130 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a re releases..*/.
2a140 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 int sqlite3_limi
2a150 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 t(sqlite3*, int
2a160 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b id, int newVal);
2a170 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2a180 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 : Run-Time Limit
2a190 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b Categories.** K
2a1a0 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 EYWORDS: {limit
2a1b0 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 category} {*limi
2a1c0 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a t categories}.**
2a1d0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
2a1e0 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f nts define vario
2a1f0 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c us performance l
2a200 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 imits.** that ca
2a210 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 n be lowered at
2a220 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b run-time using [
2a230 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
2a240 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 ..** The synopsi
2a250 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 s of the meaning
2a260 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 s of the various
2a270 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e limits is shown
2a280 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 below..** Addit
2a290 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
2a2a0 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 n is available a
2a2b0 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 t [limits | Limi
2a2c0 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a ts in SQLite]..*
2a2d0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 *.** <dl>.** [[S
2a2e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 QLITE_LIMIT_LENG
2a2f0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 TH]] ^(<dt>SQLIT
2a300 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f E_LIMIT_LENGTH</
2a310 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
2a320 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 aximum size of a
2a330 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f ny string or BLO
2a340 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 B or table row,
2a350 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a in bytes.<dd>)^.
2a360 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
2a370 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d IMIT_SQL_LENGTH]
2a380 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
2a390 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c IMIT_SQL_LENGTH<
2a3a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
2a3b0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f maximum length o
2a3c0 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 f an SQL stateme
2a3d0 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 nt, in bytes.</d
2a3e0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
2a3f0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e ITE_LIMIT_COLUMN
2a400 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
2a410 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 LIMIT_COLUMN</dt
2a420 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
2a430 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 imum number of c
2a440 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c olumns in a tabl
2a450 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 e definition or
2a460 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 in the.** result
2a470 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 set of a [SELEC
2a480 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 T] or the maximu
2a490 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 m number of colu
2a4a0 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a mns in an index.
2a4b0 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 ** or in an ORDE
2a4c0 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 R BY or GROUP BY
2a4d0 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a clause.</dd>)^.
2a4e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
2a4f0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d IMIT_EXPR_DEPTH]
2a500 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
2a510 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c IMIT_EXPR_DEPTH<
2a520 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
2a530 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 maximum depth of
2a540 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 the parse tree
2a550 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f on any expressio
2a560 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 n.</dd>)^.**.**
2a570 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 [[SQLITE_LIMIT_C
2a580 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d OMPOUND_SELECT]]
2a590 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
2a5a0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c MIT_COMPOUND_SEL
2a5b0 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ECT</dt>.** <dd>
2a5c0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
2a5d0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 er of terms in a
2a5e0 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 compound SELECT
2a5f0 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e statement.</dd>
2a600 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
2a610 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d E_LIMIT_VDBE_OP]
2a620 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
2a630 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 IMIT_VDBE_OP</dt
2a640 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
2a650 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 imum number of i
2a660 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 nstructions in a
2a670 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 virtual machine
2a680 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 program.** used
2a690 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e to implement an
2a6a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 SQL statement.
2a6b0 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 If [sqlite3_pre
2a6c0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a pare_v2()] or.**
2a6d0 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 the equivalent
2a6e0 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 tries to allocat
2a6f0 65 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 e space for more
2a700 20 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 than this many
2a710 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 opcodes.** in a
2a720 73 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20 single prepared
2a730 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 statement, an SQ
2a740 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 LITE_NOMEM error
2a750 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 is returned.</d
2a760 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
2a770 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 ITE_LIMIT_FUNCTI
2a780 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 ON_ARG]] ^(<dt>S
2a790 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 QLITE_LIMIT_FUNC
2a7a0 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a TION_ARG</dt>.**
2a7b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
2a7c0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d number of argum
2a7d0 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 ents on a functi
2a7e0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a on.</dd>)^.**.**
2a7f0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
2a800 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 ATTACHED]] ^(<dt
2a810 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 >SQLITE_LIMIT_AT
2a820 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c TACHED</dt>.** <
2a830 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
2a840 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 umber of [ATTACH
2a850 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 | attached data
2a860 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a bases].)^</dd>.*
2a870 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
2a880 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e MIT_LIKE_PATTERN
2a890 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c _LENGTH]].** ^(<
2a8a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
2a8b0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e LIKE_PATTERN_LEN
2a8c0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GTH</dt>.** <dd>
2a8d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 The maximum leng
2a8e0 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 th of the patter
2a8f0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 n argument to th
2a900 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b e [LIKE] or.** [
2a910 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e GLOB] operators.
2a920 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
2a930 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 SQLITE_LIMIT_VAR
2a940 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a IABLE_NUMBER]].*
2a950 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c * ^(<dt>SQLITE_L
2a960 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 IMIT_VARIABLE_NU
2a970 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 MBER</dt>.** <dd
2a980 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 >The maximum ind
2a990 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 ex number of any
2a9a0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 [parameter] in
2a9b0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
2a9c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 .)^.**.** [[SQLI
2a9d0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 TE_LIMIT_TRIGGER
2a9e0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 _DEPTH]] ^(<dt>S
2a9f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 QLITE_LIMIT_TRIG
2aa00 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a GER_DEPTH</dt>.*
2aa10 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
2aa20 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 m depth of recur
2aa30 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 sion for trigger
2aa40 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 s.</dd>)^.**.**
2aa50 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 [[SQLITE_LIMIT_W
2aa60 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 ORKER_THREADS]]
2aa70 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
2aa80 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 IT_WORKER_THREAD
2aa90 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 S</dt>.** <dd>Th
2aaa0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
2aab0 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f of auxiliary wo
2aac0 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61 rker threads tha
2aad0 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 t a single.** [p
2aae0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2aaf0 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 t] may start.</d
2ab00 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f d>)^.** </dl>.*/
2ab10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2ab20 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 LIMIT_LENGTH
2ab30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2ab40 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
2ab50 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 _LIMIT_SQL_LENGT
2ab60 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
2ab70 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
2ab80 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 E_LIMIT_COLUMN
2ab90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2aba0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
2abb0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 TE_LIMIT_EXPR_DE
2abc0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 PTH
2abd0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
2abe0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
2abf0 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 ND_SELECT
2ac00 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
2ac10 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f LITE_LIMIT_VDBE_
2ac20 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 OP
2ac30 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 5.#define S
2ac40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 QLITE_LIMIT_FUNC
2ac50 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 TION_ARG
2ac60 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 6.#define
2ac70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 SQLITE_LIMIT_ATT
2ac80 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 ACHED
2ac90 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 7.#define
2aca0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 SQLITE_LIMIT_LI
2acb0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 KE_PATTERN_LENGT
2acc0 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e H 8.#defin
2acd0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 e SQLITE_LIMIT_V
2ace0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 ARIABLE_NUMBER
2acf0 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 9.#defi
2ad00 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
2ad10 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 TRIGGER_DEPTH
2ad20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 10.#def
2ad30 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
2ad40 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 _WORKER_THREADS
2ad50 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 11../*
2ad60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 .** CAPI3REF: Pr
2ad70 65 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a epare Flags.**.*
2ad80 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
2ad90 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 s define various
2ada0 20 66 6c 61 67 73 20 74 68 61 74 20 63 61 6e 20 flags that can
2adb0 62 65 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a be passed into.*
2adc0 2a 20 22 70 72 65 70 46 6c 61 67 73 22 20 70 61 * "prepFlags" pa
2add0 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 5b rameter of the [
2ade0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2adf0 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 v3()] and.** [sq
2ae00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2ae10 76 33 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 v3()] interfaces
2ae20 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61 67 ..**.** New flag
2ae30 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
2ae40 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
2ae50 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a s of SQLite..**.
2ae60 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c ** <dl>.** [[SQL
2ae70 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 ITE_PREPARE_PERS
2ae80 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53 ISTENT]] ^(<dt>S
2ae90 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 QLITE_PREPARE_PE
2aea0 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a RSISTENT</dt>.**
2aeb0 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f <dd>The SQLITE_
2aec0 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 PREPARE_PERSISTE
2aed0 4e 54 20 66 6c 61 67 20 69 73 20 61 20 68 69 6e NT flag is a hin
2aee0 74 20 74 6f 20 74 68 65 20 71 75 65 72 79 20 70 t to the query p
2aef0 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74 20 74 lanner.** that t
2af00 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
2af10 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 72 65 ement will be re
2af20 74 61 69 6e 65 64 20 66 6f 72 20 61 20 6c 6f 6e tained for a lon
2af30 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20 70 72 g time and.** pr
2af40 6f 62 61 62 6c 79 20 72 65 75 73 65 64 20 6d 61 obably reused ma
2af50 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57 69 74 ny times.)^ ^Wit
2af60 68 6f 75 74 20 74 68 69 73 20 66 6c 61 67 2c 20 hout this flag,
2af70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2af80 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 _v3()].** and [s
2af90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2afa0 5f 76 33 28 29 5d 20 61 73 73 75 6d 65 20 74 68 _v3()] assume th
2afb0 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 at the prepared
2afc0 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 0a statement will .
2afd0 2a 2a 20 62 65 20 75 73 65 64 20 6a 75 73 74 20 ** be used just
2afe0 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73 74 20 once or at most
2aff0 61 20 66 65 77 20 74 69 6d 65 73 20 61 6e 64 20 a few times and
2b000 74 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75 then destroyed u
2b010 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
2b020 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c _finalize()] rel
2b030 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20 54 68 atively soon. Th
2b040 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d e current implem
2b050 65 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a 2a 2a entation acts.**
2b060 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 62 79 on this hint by
2b070 20 61 76 6f 69 64 69 6e 67 20 74 68 65 20 75 73 avoiding the us
2b080 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 e of [lookaside
2b090 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20 6e 6f memory] so as no
2b0a0 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74 65 20 t to.** deplete
2b0b0 74 68 65 20 6c 69 6d 69 74 65 64 20 73 74 6f 72 the limited stor
2b0c0 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d e of lookaside m
2b0d0 65 6d 6f 72 79 2e 20 46 75 74 75 72 65 20 76 65 emory. Future ve
2b0e0 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51 4c rsions of.** SQL
2b0f0 69 74 65 20 6d 61 79 20 61 63 74 20 6f 6e 20 74 ite may act on t
2b100 68 69 73 20 68 69 6e 74 20 64 69 66 66 65 72 65 his hint differe
2b110 6e 74 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a ntly..** </dl>.*
2b120 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2b130 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 _PREPARE_PERSIST
2b140 45 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 ENT
2b150 20 30 78 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 0x01../*.** CAP
2b160 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 I3REF: Compiling
2b170 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
2b180 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b t.** KEYWORDS: {
2b190 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f SQL statement co
2b1a0 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f mpiler}.** METHO
2b1b0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f D: sqlite3.** CO
2b1c0 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 NSTRUCTOR: sqlit
2b1d0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f e3_stmt.**.** To
2b1e0 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 execute an SQL
2b1f0 73 74 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 statement, it mu
2b200 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 st first be comp
2b210 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 iled into a byte
2b220 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d -code.** program
2b230 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 using one of th
2b240 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f ese routines. O
2b250 72 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 r, in other word
2b260 73 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 s, these routine
2b270 73 0a 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 s.** are constru
2b280 63 74 6f 72 73 20 66 6f 72 20 74 68 65 20 5b 70 ctors for the [p
2b290 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2b2a0 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a t] object..**.**
2b2b0 20 54 68 65 20 70 72 65 66 65 72 72 65 64 20 72 The preferred r
2b2c0 6f 75 74 69 6e 65 20 74 6f 20 75 73 65 20 69 73 outine to use is
2b2d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2b2e0 65 5f 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a e_v2()]. The.**
2b2f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2b300 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 e()] interface i
2b310 73 20 6c 65 67 61 63 79 20 61 6e 64 20 73 68 6f s legacy and sho
2b320 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a uld be avoided..
2b330 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
2b340 61 72 65 5f 76 33 28 29 5d 20 68 61 73 20 61 6e are_v3()] has an
2b350 20 65 78 74 72 61 20 22 70 72 65 70 46 6c 61 67 extra "prepFlag
2b360 73 22 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 s" option that i
2b370 73 20 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 s used.** for sp
2b380 65 63 69 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a ecial purposes..
2b390 2a 2a 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 **.** The use of
2b3a0 20 74 68 65 20 55 54 46 2d 38 20 69 6e 74 65 72 the UTF-8 inter
2b3b0 66 61 63 65 73 20 69 73 20 70 72 65 66 65 72 72 faces is preferr
2b3c0 65 64 2c 20 61 73 20 53 51 4c 69 74 65 20 63 75 ed, as SQLite cu
2b3d0 72 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 rrently.** does
2b3e0 61 6c 6c 20 70 61 72 73 69 6e 67 20 75 73 69 6e all parsing usin
2b3f0 67 20 55 54 46 2d 38 2e 20 20 54 68 65 20 55 54 g UTF-8. The UT
2b400 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 F-16 interfaces
2b410 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 are provided.**
2b420 61 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 as a convenience
2b430 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e . The UTF-16 in
2b440 74 65 72 66 61 63 65 73 20 77 6f 72 6b 20 62 79 terfaces work by
2b450 20 63 6f 6e 76 65 72 74 69 6e 67 20 74 68 65 0a converting the.
2b460 2a 2a 20 69 6e 70 75 74 20 74 65 78 74 20 69 6e ** input text in
2b470 74 6f 20 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 to UTF-8, then i
2b480 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 nvoking the corr
2b490 65 73 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 esponding UTF-8
2b4a0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
2b4b0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
2b4c0 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 ent, "db", is a
2b4d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2b4e0 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 tion] obtained f
2b4f0 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 rom a.** prior s
2b500 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
2b510 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
2b520 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
2b530 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 n_v2()] or.** [s
2b540 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
2b550 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 . The database
2b560 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 connection must
2b570 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c not have been cl
2b580 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 osed..**.** The
2b590 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c second argument,
2b5a0 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 "zSql", is the
2b5b0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 statement to be
2b5c0 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 compiled, encode
2b5d0 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 d.** as either U
2b5e0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 TF-8 or UTF-16.
2b5f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 The sqlite3_pre
2b600 70 61 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f pare(), sqlite3_
2b610 70 72 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a prepare_v2(),.**
2b620 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
2b630 70 61 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 pare_v3().** int
2b640 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d erfaces use UTF-
2b650 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 8, and sqlite3_p
2b660 72 65 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69 repare16(), sqli
2b670 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
2b680 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 (),.** and sqlit
2b690 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 e3_prepare16_v3(
2b6a0 29 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a ) use UTF-16..**
2b6b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 .** ^If the nByt
2b6c0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 e argument is ne
2b6d0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 gative, then zSq
2b6e0 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 l is read up to
2b6f0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 the.** first zer
2b700 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 o terminator. ^I
2b710 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 f nByte is posit
2b720 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 ive, then it is
2b730 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
2b740 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d bytes read from
2b750 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 zSql. ^If nByt
2b760 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 e is zero, then
2b770 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 no prepared.** s
2b780 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 tatement is gene
2b790 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 rated..** If the
2b7a0 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 caller knows th
2b7b0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 at the supplied
2b7c0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 string is nul-te
2b7d0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a rminated, then.*
2b7e0 2a 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 * there is a sma
2b7f0 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 ll performance a
2b800 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 dvantage to pass
2b810 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 ing an nByte par
2b820 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 ameter that.** i
2b830 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
2b840 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 bytes in the inp
2b850 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 ut string <i>inc
2b860 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 luding</i>.** th
2b870 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 e nul-terminator
2b880 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 ..**.** ^If pzTa
2b890 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 il is not NULL t
2b8a0 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d hen *pzTail is m
2b8b0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 ade to point to
2b8c0 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a the first byte.*
2b8d0 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f * past the end o
2b8e0 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 f the first SQL
2b8f0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 statement in zSq
2b900 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e l. These routin
2b910 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 es only.** compi
2b920 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 le the first sta
2b930 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 tement in zSql,
2b940 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 so *pzTail is le
2b950 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a ft pointing to.*
2b960 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 * what remains u
2b970 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a ncompiled..**.**
2b980 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 ^*ppStmt is lef
2b990 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 t pointing to a
2b9a0 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 compiled [prepar
2b9b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
2b9c0 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 at can be.** exe
2b9d0 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c cuted using [sql
2b9e0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e ite3_step()]. ^
2b9f0 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 If there is an e
2ba00 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 rror, *ppStmt is
2ba10 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e set.** to NULL.
2ba20 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 ^If the input
2ba30 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f text contains no
2ba40 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 SQL (if the inp
2ba50 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a ut is an empty.*
2ba60 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f * string or a co
2ba70 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 mment) then *ppS
2ba80 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 tmt is set to NU
2ba90 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 LL..** The calli
2baa0 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 ng procedure is
2bab0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 responsible for
2bac0 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d deleting the com
2bad0 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 piled.** SQL sta
2bae0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 tement using [sq
2baf0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
2bb00 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 ] after it has f
2bb10 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e inished with it.
2bb20 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e .** ppStmt may n
2bb30 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a ot be NULL..**.*
2bb40 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 * ^On success, t
2bb50 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 he sqlite3_prepa
2bb60 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 re() family of r
2bb70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b outines return [
2bb80 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f SQLITE_OK];.** o
2bb90 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 therwise an [err
2bba0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
2bbb0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rned..**.** The
2bbc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2bbd0 76 32 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 v2(), sqlite3_pr
2bbe0 65 70 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 epare_v3(), sqli
2bbf0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
2bc00 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 (),.** and sqlit
2bc10 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 e3_prepare16_v3(
2bc20 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 ) interfaces are
2bc30 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 recommended for
2bc40 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d all new program
2bc50 73 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 s..** The older
2bc60 69 6e 74 65 72 66 61 63 65 73 20 28 73 71 6c 69 interfaces (sqli
2bc70 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e te3_prepare() an
2bc80 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
2bc90 65 31 36 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 e16()).** are re
2bca0 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 tained for backw
2bcb0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
2bcc0 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 ty, but their us
2bcd0 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 e is discouraged
2bce0 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 ..** ^In the "vX
2bcf0 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 " interfaces, th
2bd00 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
2bd10 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 ment.** that is
2bd20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 returned (the [s
2bd30 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a qlite3_stmt] obj
2bd40 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 ect) contains a
2bd50 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f copy of the.** o
2bd60 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 riginal SQL text
2bd70 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 . This causes th
2bd80 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
2bd90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a )] interface to.
2bda0 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 ** behave differ
2bdb0 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 ently in three w
2bdc0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a ays:.**.** <ol>.
2bdd0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 ** <li>.** ^If t
2bde0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 he database sche
2bdf0 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 ma changes, inst
2be00 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 ead of returning
2be10 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
2be20 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 as it.** always
2be30 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 used to do, [sq
2be40 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
2be50 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ll automatically
2be60 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 recompile the S
2be70 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 QL.** statement
2be80 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 and try to run i
2be90 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 t again. As many
2bea0 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f as [SQLITE_MAX_
2beb0 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a SCHEMA_RETRY].**
2bec0 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 retries will oc
2bed0 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 cur before sqlit
2bee0 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 e3_step() gives
2bef0 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 up and returns a
2bf00 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 n error..** </li
2bf10 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 >.**.** <li>.**
2bf20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f ^When an error o
2bf30 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f ccurs, [sqlite3_
2bf40 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 step()] will ret
2bf50 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 urn one of the d
2bf60 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f etailed.** [erro
2bf70 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 r codes] or [ext
2bf80 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
2bf90 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 s]. ^The legacy
2bfa0 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 behavior was th
2bfb0 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 at.** [sqlite3_s
2bfc0 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c tep()] would onl
2bfd0 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 y return a gener
2bfe0 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ic [SQLITE_ERROR
2bff0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a ] result code.**
2c000 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 and the applica
2c010 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 tion would have
2c020 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 to make a second
2c030 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
2c040 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 3_reset()].** in
2c050 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 order to find t
2c060 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 he underlying ca
2c070 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c use of the probl
2c080 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 em. With the "v2
2c090 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 " prepare.** int
2c0a0 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 erfaces, the und
2c0b0 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 erlying reason f
2c0c0 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 or the error is
2c0d0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 returned immedia
2c0e0 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a tely..** </li>.*
2c0f0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 *.** <li>.** ^If
2c100 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 the specific va
2c110 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 lue bound to [pa
2c120 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 rameter | host p
2c130 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 arameter] in the
2c140 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 .** WHERE claus
2c150 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 e might influenc
2c160 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 e the choice of
2c170 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 query plan for a
2c180 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 statement,.** t
2c190 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e hen the statemen
2c1a0 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 t will be automa
2c1b0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c tically recompil
2c1c0 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 ed, as if there
2c1d0 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 had been .** a s
2c1e0 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e chema change, on
2c1f0 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c the first [sql
2c200 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c ite3_step()] cal
2c210 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 l following any
2c220 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 change.** to the
2c230 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 [sqlite3_bind_t
2c240 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 ext | bindings]
2c250 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 of that [paramet
2c260 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 er]. .** ^The sp
2c270 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 ecific value of
2c280 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 WHERE-clause [pa
2c290 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 rameter] might i
2c2a0 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a nfluence the .**
2c2b0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 choice of query
2c2c0 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 plan if the par
2c2d0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 ameter is the le
2c2e0 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 ft-hand side of
2c2f0 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b a [LIKE].** or [
2c300 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f GLOB] operator o
2c310 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 r if the paramet
2c320 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 er is compared t
2c330 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c o an indexed col
2c340 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b umn.** and the [
2c350 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 SQLITE_ENABLE_ST
2c360 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d AT3] compile-tim
2c370 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 e option is enab
2c380 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a led..** </li>.**
2c390 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e </ol>.**.** <p>
2c3a0 5e 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 ^sqlite3_prepare
2c3b0 5f 76 33 28 29 20 64 69 66 66 65 72 73 20 66 72 _v3() differs fr
2c3c0 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 om sqlite3_prepa
2c3d0 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20 re_v2() only in
2c3e0 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78 having.** the ex
2c3f0 74 72 61 20 70 72 65 70 46 6c 61 67 73 20 70 61 tra prepFlags pa
2c400 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 69 rameter, which i
2c410 73 20 61 20 62 69 74 20 61 72 72 61 79 20 63 6f s a bit array co
2c420 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f nsisting of zero
2c430 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 or.** more of t
2c440 68 65 20 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 he [SQLITE_PREPA
2c450 52 45 5f 50 45 52 53 49 53 54 45 4e 54 7c 53 51 RE_PERSISTENT|SQ
2c460 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20 LITE_PREPARE_*]
2c470 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 flags. ^The.**
2c480 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2c490 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 v2() interface w
2c4a0 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 74 68 65 orks exactly the
2c4b0 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 same as.** sqli
2c4c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 te3_prepare_v3()
2c4d0 20 77 69 74 68 20 61 20 7a 65 72 6f 20 70 72 65 with a zero pre
2c4e0 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 pFlags parameter
2c4f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2c500 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 _prepare(. sqli
2c510 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
2c520 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
2c530 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
2c540 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 t char *zSql,
2c550 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
2c560 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f ment, UTF-8 enco
2c570 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
2c580 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
2c590 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
2c5a0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
2c5b0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
2c5c0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
2c5d0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
2c5e0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
2c5f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 const char **pzT
2c600 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
2c610 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
2c620 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
2c630 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 l */.);.int sqli
2c640 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a te3_prepare_v2(.
2c650 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
2c660 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
2c670 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
2c680 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
2c690 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
2c6a0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
2c6b0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 8 encoded */. i
2c6c0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
2c6d0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
2c6e0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
2c6f0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
2c700 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
2c710 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
2c720 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
2c730 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
2c740 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
2c750 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
2c760 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
2c770 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e of zSql */.);.in
2c780 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
2c790 65 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 e_v3(. sqlite3
2c7a0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
2c7b0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
2c7c0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
2c7d0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 ar *zSql,
2c7e0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
2c7f0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 , UTF-8 encoded
2c800 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 */. int nByte,
2c810 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
2c820 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f Maximum length o
2c830 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e f zSql in bytes.
2c840 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 */. unsigned i
2c850 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a nt prepFlags, /*
2c860 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 Zero or more SQ
2c870 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c LITE_PREPARE_ fl
2c880 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 ags */. sqlite3
2c890 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
2c8a0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
2c8b0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
2c8c0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 onst char **pzTa
2c8d0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
2c8e0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
2c8f0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
2c900 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
2c910 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 e3_prepare16(.
2c920 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
2c930 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
2c940 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
2c950 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c const void *zSql
2c960 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
2c970 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 tatement, UTF-16
2c980 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
2c990 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
2c9a0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
2c9b0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
2c9c0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
2c9d0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
2c9e0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
2c9f0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
2ca00 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
2ca10 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
2ca20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
2ca30 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
2ca40 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 f zSql */.);.int
2ca50 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
2ca60 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 16_v2(. sqlite3
2ca70 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
2ca80 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
2ca90 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
2caa0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 oid *zSql,
2cab0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
2cac0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 t, UTF-16 encode
2cad0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
2cae0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
2caf0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
2cb00 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
2cb10 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
2cb20 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
2cb30 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
2cb40 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
2cb50 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 nst void **pzTai
2cb60 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
2cb70 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
2cb80 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
2cb90 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 */.);.int sqlite
2cba0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a 3_prepare16_v3(.
2cbb0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
2cbc0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
2cbd0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
2cbe0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 const void *zS
2cbf0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
2cc00 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
2cc10 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 16 encoded */.
2cc20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
2cc30 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
2cc40 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
2cc50 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
2cc60 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 unsigned int pr
2cc70 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f epFlags, /* Zero
2cc80 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f or more SQLITE_
2cc90 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a PREPARE_ flags *
2cca0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
2ccb0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
2ccc0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
2ccd0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
2cce0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
2ccf0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
2cd00 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
2cd10 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
2cd20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2cd30 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 F: Retrieving St
2cd40 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d atement SQL.** M
2cd50 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
2cd60 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 tmt.**.** ^The s
2cd70 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e qlite3_sql(P) in
2cd80 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2cd90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 a pointer to a c
2cda0 6f 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 opy of the UTF-8
2cdb0 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 .** SQL text use
2cdc0 64 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 d to create [pre
2cdd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2cde0 20 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 P if P was.** c
2cdf0 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 reated by [sqlit
2ce00 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2ce10 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 , [sqlite3_prepa
2ce20 72 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 re_v3()],.** [sq
2ce30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2ce40 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 v2()], or [sqlit
2ce50 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 e3_prepare16_v3(
2ce60 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 )]..** ^The sqli
2ce70 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c te3_expanded_sql
2ce80 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (P) interface re
2ce90 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
2cea0 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 to a UTF-8.** st
2ceb0 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 ring containing
2cec0 74 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 the SQL text of
2ced0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2cee0 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f nt P with.** [bo
2cef0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 und parameters]
2cf00 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 expanded..**.**
2cf10 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 ^(For example, i
2cf20 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 f a prepared sta
2cf30 74 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 tement is create
2cf40 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a d using the SQL.
2cf50 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 ** text "SELECT
2cf60 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 $abc,:xyz" and i
2cf70 66 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 f parameter $abc
2cf80 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 is bound to int
2cf90 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 eger 2345.** and
2cfa0 20 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 parameter :xyz
2cfb0 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e is unbound, then
2cfc0 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 sqlite3_sql() w
2cfd0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 ill return.** th
2cfe0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e e original strin
2cff0 67 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c g, "SELECT $abc,
2d000 3a 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 :xyz" but sqlite
2d010 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 3_expanded_sql()
2d020 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 .** will return
2d030 22 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c "SELECT 2345,NUL
2d040 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 L".)^.**.** ^The
2d050 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 sqlite3_expande
2d060 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 d_sql() interfac
2d070 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 e returns NULL i
2d080 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d f insufficient m
2d090 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 emory.** is avai
2d0a0 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 lable to hold th
2d0b0 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 e result, or if
2d0c0 74 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 the result would
2d0d0 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 exceed the.** t
2d0e0 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e he maximum strin
2d0f0 67 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 g length determi
2d100 6e 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 ned by the [SQLI
2d110 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d TE_LIMIT_LENGTH]
2d120 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ..**.** ^The [SQ
2d130 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f LITE_TRACE_SIZE_
2d140 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 LIMIT] compile-t
2d150 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 ime option limit
2d160 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a s the size of.**
2d170 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 bound parameter
2d180 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 expansions. ^T
2d190 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f he [SQLITE_OMIT_
2d1a0 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 TRACE] compile-t
2d1b0 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 ime.** option ca
2d1c0 75 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 uses sqlite3_exp
2d1d0 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 anded_sql() to a
2d1e0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c lways return NUL
2d1f0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 L..**.** ^The st
2d200 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 ring returned by
2d210 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 sqlite3_sql(P)
2d220 69 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 is managed by SQ
2d230 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 Lite and is.** a
2d240 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 utomatically fre
2d250 65 64 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 ed when the prep
2d260 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 ared statement i
2d270 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 s finalized..**
2d280 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 ^The string retu
2d290 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
2d2a0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c expanded_sql(P),
2d2b0 20 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 on the other ha
2d2c0 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e nd,.** is obtain
2d2d0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
2d2e0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d _malloc()] and m
2d2f0 75 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74 ust be free by t
2d300 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a he application.*
2d310 2a 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 * by passing it
2d320 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 to [sqlite3_free
2d330 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ()]..*/.const ch
2d340 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 ar *sqlite3_sql(
2d350 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
2d360 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 tmt);.char *sqli
2d370 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c te3_expanded_sql
2d380 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
2d390 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
2d3a0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e PI3REF: Determin
2d3b0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 e If An SQL Stat
2d3c0 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 ement Writes The
2d3d0 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 Database.** MET
2d3e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
2d3f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c t.**.** ^The sql
2d400 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
2d410 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 ly(X) interface
2d420 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f returns true (no
2d430 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e n-zero) if.** an
2d440 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 d only if the [p
2d450 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2d460 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 t] X makes no di
2d470 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a rect changes to.
2d480 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f ** the content o
2d490 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 f the database f
2d4a0 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 ile..**.** Note
2d4b0 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f that [applicatio
2d4c0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
2d4d0 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b nctions] or.** [
2d4e0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 virtual tables]
2d4f0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 might change the
2d500 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 database indire
2d510 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 ctly as a side e
2d520 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f ffect. .** ^(Fo
2d530 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e r example, if an
2d540 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 application def
2d550 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 ines a function
2d560 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a "eval()" that .*
2d570 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 * calls [sqlite3
2d580 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 _exec()], then t
2d590 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c he following SQL
2d5a0 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 statement would
2d5b0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 .** change the d
2d5c0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 atabase file thr
2d5d0 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 ough side-effect
2d5e0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
2d5f0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 uote><pre>.**
2d600 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 SELECT eval('DE
2d610 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 LETE FROM t1') F
2d620 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 ROM t2;.** </pre
2d630 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
2d640 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 *.** But because
2d650 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 the [SELECT] st
2d660 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 atement does not
2d670 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 change the data
2d680 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 base file.** dir
2d690 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 ectly, sqlite3_s
2d6a0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 tmt_readonly() w
2d6b0 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 ould still retur
2d6c0 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 n true.)^.**.**
2d6d0 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e ^Transaction con
2d6e0 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 trol statements
2d6f0 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c such as [BEGIN],
2d700 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c [COMMIT], [ROLL
2d710 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 BACK],.** [SAVEP
2d720 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 OINT], and [RELE
2d730 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 ASE] cause sqlit
2d740 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
2d750 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 () to return tru
2d760 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 e,.** since the
2d770 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 statements thems
2d780 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 elves do not act
2d790 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 ually modify the
2d7a0 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a database but.**
2d7b0 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e rather they con
2d7c0 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 trol the timing
2d7d0 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 of when other st
2d7e0 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 atements modify
2d7f0 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 the .** database
2d800 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d . ^The [ATTACH]
2d810 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 and [DETACH] st
2d820 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 atements also ca
2d830 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 use.** sqlite3_s
2d840 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 tmt_readonly() t
2d850 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 o return true si
2d860 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 nce, while those
2d870 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 statements.** c
2d880 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 hange the config
2d890 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 uration of a dat
2d8a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2d8b0 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 , they do not ma
2d8c0 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 ke .** changes t
2d8d0 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 o the content of
2d8e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
2d8f0 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 les on disk..**
2d900 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d ^The sqlite3_stm
2d910 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 t_readonly() int
2d920 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
2d930 72 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 rue for [BEGIN]
2d940 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d since.** [BEGIN]
2d950 20 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74 merely sets int
2d960 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 ernal flags, but
2d970 20 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 the [BEGIN|BEGI
2d980 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 N IMMEDIATE] and
2d990 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e .** [BEGIN|BEGIN
2d9a0 20 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d EXCLUSIVE] comm
2d9b0 61 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68 ands do touch th
2d9c0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 73 e database and s
2d9d0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d o.** sqlite3_stm
2d9e0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 t_readonly() ret
2d9f0 75 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74 urns false for t
2da00 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a hose commands..*
2da10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 /.int sqlite3_st
2da20 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 mt_readonly(sqli
2da30 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2da40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2da50 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
2da60 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
2da70 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 ment Has Been Re
2da80 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 set.** METHOD: s
2da90 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2daa0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 * ^The sqlite3_s
2dab0 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 tmt_busy(S) inte
2dac0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 rface returns tr
2dad0 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 ue (non-zero) if
2dae0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
2daf0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 d statement] S h
2db00 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 as been stepped
2db10 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 at least once us
2db20 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ing .** [sqlite3
2db30 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 _step(S)] but ha
2db40 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f s neither run to
2db50 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 completion (ret
2db60 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 urned.** [SQLITE
2db70 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c _DONE] from [sql
2db80 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e ite3_step(S)]) n
2db90 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 or.** been reset
2dba0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
2dbb0 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 reset(S)]. ^The
2dbc0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 sqlite3_stmt_bu
2dbd0 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 sy(S).** interfa
2dbe0 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 ce returns false
2dbf0 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 if S is a NULL
2dc00 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 pointer. If S i
2dc10 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c s not a .** NULL
2dc20 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 pointer and is
2dc30 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f not a pointer to
2dc40 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 a valid [prepar
2dc50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
2dc60 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 object, then th
2dc70 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e e behavior is un
2dc80 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 defined and prob
2dc90 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 ably undesirable
2dca0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
2dcb0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 erface can be us
2dcc0 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f ed in combinatio
2dcd0 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f n [sqlite3_next_
2dce0 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f stmt()].** to lo
2dcf0 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 cate all prepare
2dd00 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 d statements ass
2dd10 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 ociated with a d
2dd20 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e atabase .** conn
2dd30 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 ection that are
2dd40 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 in need of being
2dd50 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 reset. This ca
2dd60 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f n be used,.** fo
2dd70 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 r example, in di
2dd80 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 agnostic routine
2dd90 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 s to search for
2dda0 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 prepared .** sta
2ddb0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 tements that are
2ddc0 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 holding a trans
2ddd0 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a action open..*/.
2dde0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 int sqlite3_stmt
2ddf0 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 _busy(sqlite3_st
2de00 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
2de10 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c I3REF: Dynamical
2de20 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f ly Typed Value O
2de30 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 bject.** KEYWORD
2de40 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 S: {protected sq
2de50 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e lite3_value} {un
2de60 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2de70 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 3_value}.**.** S
2de80 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 QLite uses the s
2de90 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
2dea0 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 ect to represent
2deb0 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 all values.** t
2dec0 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 hat can be store
2ded0 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 d in a database
2dee0 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 table. SQLite us
2def0 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e es dynamic typin
2df00 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c g.** for the val
2df10 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 ues it stores.
2df20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 ^Values stored i
2df30 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 n sqlite3_value
2df40 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 objects.** can b
2df50 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 e integers, floa
2df60 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 ting point value
2df70 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 s, strings, BLOB
2df80 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a s, or NULL..**.*
2df90 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c * An sqlite3_val
2dfa0 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 ue object may be
2dfb0 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 either "protect
2dfc0 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 ed" or "unprotec
2dfd0 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e ted"..** Some in
2dfe0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 terfaces require
2dff0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c a protected sql
2e000 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 ite3_value. Oth
2e010 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a er interfaces.**
2e020 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 will accept eit
2e030 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 her a protected
2e040 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 or an unprotecte
2e050 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
2e060 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 .** Every interf
2e070 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 ace that accepts
2e080 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 sqlite3_value a
2e090 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 rguments specifi
2e0a0 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 es.** whether or
2e0b0 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 not it requires
2e0c0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c a protected sql
2e0d0 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 ite3_value. The
2e0e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
2e0f0 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 ue_dup()] interf
2e100 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ace can be used
2e110 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e to construct a n
2e120 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 ew .** protected
2e130 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 sqlite3_value f
2e140 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 rom an unprotect
2e150 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
2e160 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d ..**.** The term
2e170 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e s "protected" an
2e180 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 d "unprotected"
2e190 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 refer to whether
2e1a0 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 or not.** a mut
2e1b0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 ex is held. An
2e1c0 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 internal mutex i
2e1d0 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f s held for a pro
2e1e0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
2e1f0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 3_value object b
2e200 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 ut no mutex is h
2e210 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f eld for an unpro
2e220 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
2e230 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 3_value object.
2e240 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f If SQLite is co
2e250 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e mpiled to be sin
2e260 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 gle-threaded.**
2e270 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 (with [SQLITE_TH
2e280 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 READSAFE=0] and
2e290 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 with [sqlite3_th
2e2a0 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 readsafe()] retu
2e2b0 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 rning 0).** or i
2e2c0 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 f SQLite is run
2e2d0 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 in one of reduce
2e2e0 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a d mutex modes .*
2e2f0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
2e300 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f _SINGLETHREAD] o
2e310 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 r [SQLITE_CONFIG
2e320 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a _MULTITHREAD].**
2e330 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e then there is n
2e340 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 o distinction be
2e350 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 tween protected
2e360 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a and unprotected.
2e370 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
2e380 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 objects and the
2e390 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e y can be used in
2e3a0 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 terchangeably.
2e3b0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 However,.** for
2e3c0 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 maximum code por
2e3d0 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 tability it is r
2e3e0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
2e3f0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
2e400 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 still make the d
2e410 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 istinction betwe
2e420 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 en protected and
2e430 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 unprotected.**
2e440 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2e450 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 jects even when
2e460 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 not strictly req
2e470 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 uired..**.** ^Th
2e480 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
2e490 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 objects that are
2e4a0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d passed as param
2e4b0 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a eters into the.*
2e4c0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
2e4d0 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e of [application
2e4e0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
2e4f0 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 ctions] are prot
2e500 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 ected..** ^The s
2e510 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
2e520 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a ect returned by.
2e530 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
2e540 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 mn_value()] is u
2e550 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 nprotected..** U
2e560 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
2e570 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
2e580 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 may only be use
2e590 64 20 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a d as arguments.*
2e5a0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 * to [sqlite3_re
2e5b0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b sult_value()], [
2e5c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c sqlite3_bind_val
2e5d0 75 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 ue()], and.** [s
2e5e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 qlite3_value_dup
2e5f0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c ()]..** The [sql
2e600 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 ite3_value_blob
2e610 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f | sqlite3_value_
2e620 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f type()] family o
2e630 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 f.** interfaces
2e640 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 require protecte
2e650 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
2e660 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 objects..*/.type
2e670 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
2e680 65 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 e3_value sqlite3
2e690 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 _value;../*.** C
2e6a0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e API3REF: SQL Fun
2e6b0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 ction Context Ob
2e6c0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ject.**.** The c
2e6d0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 ontext in which
2e6e0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 an SQL function
2e6f0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 executes is stor
2e700 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 ed in an.** sqli
2e710 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 te3_context obje
2e720 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 ct. ^A pointer
2e730 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f to an sqlite3_co
2e740 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 ntext object.**
2e750 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 is always first
2e760 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 parameter to [ap
2e770 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2e780 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
2e790 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
2e7a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
2e7b0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
2e7c0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 entation will pa
2e7d0 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 ss this.** point
2e7e0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 er through into
2e7f0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
2e800 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 3_result_int | s
2e810 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d qlite3_result()]
2e820 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 ,.** [sqlite3_ag
2e830 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
2e840 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 )], [sqlite3_use
2e850 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 r_data()],.** [s
2e860 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 qlite3_context_d
2e870 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 b_handle()], [sq
2e880 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
2e890 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 a()],.** and/or
2e8a0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 [sqlite3_set_aux
2e8b0 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 data()]..*/.type
2e8c0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
2e8d0 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 e3_context sqlit
2e8e0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a e3_context;../*.
2e8f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e ** CAPI3REF: Bin
2e900 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 ding Values To P
2e910 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
2e920 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ts.** KEYWORDS:
2e930 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d {host parameter}
2e940 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
2e950 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 s} {host paramet
2e960 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 er name}.** KEYW
2e970 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d ORDS: {SQL param
2e980 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d eter} {SQL param
2e990 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 eters} {paramete
2e9a0 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 r binding}.** ME
2e9b0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2e9c0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 mt.**.** ^(In th
2e9d0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
2e9e0 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 text input to [s
2e9f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2ea00 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 2()] and its var
2ea10 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 iants,.** litera
2ea20 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 ls may be replac
2ea30 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 ed by a [paramet
2ea40 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 er] that matches
2ea50 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e one of followin
2ea60 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a g.** templates:.
2ea70 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
2ea80 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f i> ?.** <li> ?
2ea90 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 NNN.** <li> :VV
2eaa0 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a V.** <li> @VVV.
2eab0 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a ** <li> $VVV.**
2eac0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 </ul>.**.** In
2ead0 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 the templates ab
2eae0 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 ove, NNN represe
2eaf0 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c nts an integer l
2eb00 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 iteral,.** and V
2eb10 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e VV represents an
2eb20 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 alphanumeric id
2eb30 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 entifier.)^ ^Th
2eb40 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 e values of thes
2eb50 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 e.** parameters
2eb60 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f (also called "ho
2eb70 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d st parameter nam
2eb80 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 es" or "SQL para
2eb90 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 meters").** can
2eba0 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 be set using the
2ebb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
2ebc0 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e ) routines defin
2ebd0 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e ed here..**.** ^
2ebe0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
2ebf0 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 nt to the sqlite
2ec00 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
2ec10 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a nes is always.**
2ec20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
2ec30 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d e [sqlite3_stmt]
2ec40 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 object returned
2ec50 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 from.** [sqlite
2ec60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2ec70 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e or its variants.
2ec80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f .**.** ^The seco
2ec90 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 nd argument is t
2eca0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 he index of the
2ecb0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f SQL parameter to
2ecc0 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 be set..** ^The
2ecd0 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 leftmost SQL pa
2ece0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 rameter has an i
2ecf0 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 ndex of 1. ^Whe
2ed00 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 n the same named
2ed10 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 .** SQL paramete
2ed20 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 r is used more t
2ed30 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 han once, second
2ed40 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a and subsequent.
2ed50 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 ** occurrences h
2ed60 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 ave the same ind
2ed70 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ex as the first
2ed80 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e occurrence..** ^
2ed90 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 The index for na
2eda0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 med parameters c
2edb0 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 an be looked up
2edc0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 using the.** [sq
2edd0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2ede0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 eter_index()] AP
2edf0 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e I if desired. ^
2ee00 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 The index.** for
2ee10 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 "?NNN" paramete
2ee20 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 rs is the value
2ee30 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 of NNN..** ^The
2ee40 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 NNN value must b
2ee50 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 e between 1 and
2ee60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d the [sqlite3_lim
2ee70 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 it()].** paramet
2ee80 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 er [SQLITE_LIMIT
2ee90 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
2eea0 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 ] (default value
2eeb0 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 : 999)..**.** ^T
2eec0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
2eed0 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 t is the value t
2eee0 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 o bind to the pa
2eef0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 rameter..** ^If
2ef00 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
2ef10 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ter to sqlite3_b
2ef20 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 ind_text() or sq
2ef30 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
2ef40 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 6().** or sqlite
2ef50 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 3_bind_blob() is
2ef60 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
2ef70 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 then the fourth
2ef80 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 parameter.** is
2ef90 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 ignored and the
2efa0 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 end result is th
2efb0 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 e same as sqlite
2efc0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 3_bind_null()..*
2efd0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 *.** ^(In those
2efe0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 routines that ha
2eff0 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 ve a fourth argu
2f000 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 ment, its value
2f010 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 is the.** number
2f020 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
2f030 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 parameter. To
2f040 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 be clear: the va
2f050 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 lue is the.** nu
2f060 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 mber of <u>bytes
2f070 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 </u> in the valu
2f080 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 e, not the numbe
2f090 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e r of characters.
2f0a0 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f )^.** ^If the fo
2f0b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
2f0c0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 o sqlite3_bind_t
2f0d0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ext() or sqlite3
2f0e0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a _bind_text16().*
2f0f0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 * is negative, t
2f100 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f hen the length o
2f110 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a f the string is.
2f120 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
2f130 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 bytes up to the
2f140 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d first zero term
2f150 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 inator..** If th
2f160 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
2f170 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 er to sqlite3_bi
2f180 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 nd_blob() is neg
2f190 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 ative, then.** t
2f1a0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
2f1b0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 ndefined..** If
2f1c0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 a non-negative f
2f1d0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
2f1e0 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 is provided to s
2f1f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2f200 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
2f210 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f _bind_text16() o
2f220 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 r sqlite3_bind_t
2f230 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 ext64() then.**
2f240 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d that parameter m
2f250 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 ust be the byte
2f260 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 offset.** where
2f270 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 the NUL terminat
2f280 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 or would occur a
2f290 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 ssuming the stri
2f2a0 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 ng were NUL.** t
2f2b0 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 erminated. If a
2f2c0 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 ny NUL character
2f2d0 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 s occur at byte
2f2e0 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 offsets less tha
2f2f0 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 n .** the value
2f300 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 of the fourth pa
2f310 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 rameter then the
2f320 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e resulting strin
2f330 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 g value will.**
2f340 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 contain embedded
2f350 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 NULs. The resu
2f360 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e lt of expression
2f370 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 s involving stri
2f380 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 ngs.** with embe
2f390 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 dded NULs is und
2f3a0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 efined..**.** ^T
2f3b0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
2f3c0 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e t to the BLOB an
2f3d0 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 d string binding
2f3e0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 interfaces.** i
2f3f0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 s a destructor u
2f400 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f sed to dispose o
2f410 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a f the BLOB or.**
2f420 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 string after SQ
2f430 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 Lite has finishe
2f440 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 d with it. ^The
2f450 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 destructor is c
2f460 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 alled.** to disp
2f470 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 ose of the BLOB
2f480 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 or string even i
2f490 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 f the call to bi
2f4a0 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a nd API fails..**
2f4b0 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 ^If the fifth a
2f4c0 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 rgument is.** th
2f4d0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 e special value
2f4e0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c [SQLITE_STATIC],
2f4f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 then SQLite ass
2f500 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a umes that the.**
2f510 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
2f520 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e in static, unman
2f530 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 aged space and d
2f540 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 oes not need to
2f550 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 be freed..** ^If
2f560 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d the fifth argum
2f570 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 ent has the valu
2f580 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 e [SQLITE_TRANSI
2f590 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 ENT], then.** SQ
2f5a0 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f Lite makes its o
2f5b0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 wn private copy
2f5c0 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 of the data imme
2f5d0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a diately, before.
2f5e0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ** the sqlite3_b
2f5f0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 ind_*() routine
2f600 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e returns..**.** ^
2f610 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 The sixth argume
2f620 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 nt to sqlite3_bi
2f630 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 nd_text64() must
2f640 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 be one of.** [S
2f650 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 QLITE_UTF8], [SQ
2f660 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 LITE_UTF16], [SQ
2f670 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f LITE_UTF16BE], o
2f680 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c r [SQLITE_UTF16L
2f690 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 E].** to specify
2f6a0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 the encoding of
2f6b0 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 the text in the
2f6c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
2f6d0 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 . If.** the six
2f6e0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 th argument to s
2f6f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2f700 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 64() is not one
2f710 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 of the.** allowe
2f720 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 d values shown a
2f730 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 bove, or if the
2f740 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 text encoding is
2f750 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 different.** fr
2f760 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 om the encoding
2f770 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
2f780 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 sixth parameter
2f790 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
2f7a0 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 ior.** is undefi
2f7b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
2f7c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 sqlite3_bind_zer
2f7d0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 oblob() routine
2f7e0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 binds a BLOB of
2f7f0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a length N that.**
2f800 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 is filled with
2f810 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f zeroes. ^A zero
2f820 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 blob uses a fixe
2f830 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f d amount of memo
2f840 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 ry.** (just an i
2f850 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 nteger to hold i
2f860 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 ts size) while i
2f870 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 t is being proce
2f880 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f ssed..** Zeroblo
2f890 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 bs are intended
2f8a0 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 to serve as plac
2f8b0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f eholders for BLO
2f8c0 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 Bs whose.** cont
2f8d0 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 ent is later wri
2f8e0 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 tten using.** [s
2f8f0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e qlite3_blob_open
2f900 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 | incremental B
2f910 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 LOB I/O] routine
2f920 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 s..** ^A negativ
2f930 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 e value for the
2f940 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 zeroblob results
2f950 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 in a zero-lengt
2f960 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 h BLOB..**.** ^T
2f970 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
2f980 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c pointer(S,I,P,T,
2f990 44 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73 65 D) routine cause
2f9a0 73 20 74 68 65 20 49 2d 74 68 20 70 61 72 61 6d s the I-th param
2f9b0 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 eter in.** [prep
2f9c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2f9d0 53 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51 4c S to have an SQL
2f9e0 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 value of NULL,
2f9f0 62 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a but to also be.*
2fa00 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
2fa10 68 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50 20 h the pointer P
2fa20 6f 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20 69 of type T. ^D i
2fa30 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 s either a NULL
2fa40 70 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20 pointer or.** a
2fa50 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 pointer to a des
2fa60 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e tructor function
2fa70 20 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65 20 for P. ^SQLite
2fa80 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a will invoke the.
2fa90 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 ** destructor D
2faa0 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 with a single ar
2fab0 67 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65 6e gument of P when
2fac0 20 69 74 20 69 73 20 66 69 6e 69 73 68 65 64 20 it is finished
2fad0 75 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65 using.** P. The
2fae0 20 54 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f T parameter sho
2faf0 75 6c 64 20 62 65 20 61 20 73 74 61 74 69 63 20 uld be a static
2fb00 73 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61 62 string, preferab
2fb10 6c 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c ly a string.** l
2fb20 69 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c 69 iteral. The sqli
2fb30 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 te3_bind_pointer
2fb40 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 () routine is pa
2fb50 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f rt of the.** [po
2fb60 69 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69 6e inter passing in
2fb70 74 65 72 66 61 63 65 5d 20 61 64 64 65 64 20 66 terface] added f
2fb80 6f 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e 30 or SQLite 3.20.0
2fb90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 ..**.** ^If any
2fba0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 of the sqlite3_b
2fbb0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 ind_*() routines
2fbc0 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 are called with
2fbd0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a a NULL pointer.
2fbe0 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 ** for the [prep
2fbf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2fc00 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 or with a prepar
2fc10 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 ed statement for
2fc20 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 which.** [sqlit
2fc30 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 e3_step()] has b
2fc40 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 een called more
2fc50 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 recently than [s
2fc60 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c qlite3_reset()],
2fc70 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c .** then the cal
2fc80 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 l will return [S
2fc90 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
2fca0 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 If any sqlite3_b
2fcb0 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e ind_().** routin
2fcc0 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 e is passed a [p
2fcd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2fce0 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e t] that has been
2fcf0 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a finalized, the.
2fd00 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 ** result is und
2fd10 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 efined and proba
2fd20 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a bly harmful..**.
2fd30 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 ** ^Bindings are
2fd40 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 not cleared by
2fd50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 the [sqlite3_res
2fd60 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a et()] routine..*
2fd70 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d * ^Unbound param
2fd80 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 eters are interp
2fd90 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a reted as NULL..*
2fda0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2fdb0 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 3_bind_* routine
2fdc0 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 s return [SQLITE
2fdd0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 _OK] on success
2fde0 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 or an.** [error
2fdf0 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e code] if anythin
2fe00 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a g goes wrong..**
2fe10 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 ^[SQLITE_TOOBIG
2fe20 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 ] might be retur
2fe30 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 ned if the size
2fe40 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 of a string or B
2fe50 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c LOB.** exceeds l
2fe60 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 imits imposed by
2fe70 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d [sqlite3_limit]
2fe80 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c ([SQLITE_LIMIT_L
2fe90 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 ENGTH]) or.** [S
2fea0 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 QLITE_MAX_LENGTH
2feb0 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 ]..** ^[SQLITE_R
2fec0 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 ANGE] is returne
2fed0 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 d if the paramet
2fee0 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f er.** index is o
2fef0 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b ut of range. ^[
2ff00 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 SQLITE_NOMEM] is
2ff10 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c returned if mal
2ff20 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a loc() fails..**.
2ff30 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
2ff40 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2ff50 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a eter_count()],.*
2ff60 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2ff70 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 parameter_name()
2ff80 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
2ff90 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
2ffa0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 ndex()]..*/.int
2ffb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2ffc0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
2ffd0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 int, const void
2ffe0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a *, int n, void(*
2fff0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 )(void*));.int s
30000 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
30010 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 64(sqlite3_stmt*
30020 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
30030 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 d*, sqlite3_uint
30040 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 64,.
30050 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 void
30060 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 (*)(void*));.int
30070 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f sqlite3_bind_do
30080 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d uble(sqlite3_stm
30090 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 t*, int, double)
300a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
300b0 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 nd_int(sqlite3_s
300c0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b tmt*, int, int);
300d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
300e0 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f d_int64(sqlite3_
300f0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 stmt*, int, sqli
30100 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 te3_int64);.int
30110 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c sqlite3_bind_nul
30120 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c l(sqlite3_stmt*,
30130 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 int);.int sqlit
30140 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c e3_bind_text(sql
30150 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 ite3_stmt*,int,c
30160 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 onst char*,int,v
30170 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
30180 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
30190 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f _text16(sqlite3_
301a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
301b0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f t void*, int, vo
301c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 id(*)(void*));.i
301d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
301e0 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 text64(sqlite3_s
301f0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
30200 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f char*, sqlite3_
30210 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 uint64,.
30220 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
30230 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c void(*)(void*),
30240 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 unsigned char e
30250 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 ncoding);.int sq
30260 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 lite3_bind_value
30270 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
30280 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 int, const sqlit
30290 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
302a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 sqlite3_bind_poi
302b0 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d nter(sqlite3_stm
302c0 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 t*, int, void*,
302d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f 69 64 const char*,void
302e0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 (*)(void*));.int
302f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 sqlite3_bind_ze
30300 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 roblob(sqlite3_s
30310 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e tmt*, int, int n
30320 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
30330 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 ind_zeroblob64(s
30340 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
30350 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 t, sqlite3_uint6
30360 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 4);../*.** CAPI3
30370 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 REF: Number Of S
30380 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a QL Parameters.**
30390 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
303a0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 _stmt.**.** ^Thi
303b0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 s routine can be
303c0 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 used to find th
303d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c e number of [SQL
303e0 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 parameters].**
303f0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 in a [prepared s
30400 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 tatement]. SQL
30410 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 parameters are t
30420 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 okens of the.**
30430 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 form "?", "?NNN"
30440 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 , ":AAA", "$AAA"
30450 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 , or "@AAA" that
30460 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 serve as.** pla
30470 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 ceholders for va
30480 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 lues that are [s
30490 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
304a0 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 | bound].** to
304b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 the parameters a
304c0 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a t a later time..
304d0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 **.** ^(This rou
304e0 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 tine actually re
304f0 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 turns the index
30500 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 of the largest (
30510 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 rightmost).** pa
30520 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c rameter. For all
30530 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e forms except ?N
30540 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f NN, this will co
30550 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a rrespond to the.
30560 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 ** number of uni
30570 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 que parameters.
30580 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f If parameters o
30590 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 f the ?NNN form
305a0 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 are used,.** the
305b0 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 re may be gaps i
305c0 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a n the list.)^.**
305d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
305e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
305f0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
30600 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
30610 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
30620 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 e()], and.** [sq
30630 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
30640 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a eter_index()]..*
30650 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 /.int sqlite3_bi
30660 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
30670 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a nt(sqlite3_stmt*
30680 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
30690 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f EF: Name Of A Ho
306a0 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 st Parameter.**
306b0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
306c0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 stmt.**.** ^The
306d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
306e0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 ameter_name(P,N)
306f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
30700 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f ns.** the name o
30710 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 f the N-th [SQL
30720 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 parameter] in th
30730 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
30740 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 ement] P..** ^(S
30750 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 QL parameters of
30760 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 the form "?NNN"
30770 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 or ":AAA" or "@
30780 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a AAA" or "$AAA".*
30790 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 * have a name wh
307a0 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e ich is the strin
307b0 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 g "?NNN" or ":AA
307c0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 A" or "@AAA" or
307d0 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 "$AAA".** respec
307e0 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 tively..** In ot
307f0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 her words, the i
30800 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 nitial ":" or "$
30810 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a " or "@" or "?".
30820 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 ** is included a
30830 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 s part of the na
30840 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 me.)^.** ^Parame
30850 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d ters of the form
30860 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 "?" without a f
30870 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 ollowing integer
30880 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a have no name.**
30890 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 and are referre
308a0 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 d to as "nameles
308b0 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 s" or "anonymous
308c0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a parameters"..**
308d0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 .** ^The first h
308e0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 ost parameter ha
308f0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c s an index of 1,
30900 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 not 0..**.** ^I
30910 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 f the value N is
30920 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 out of range or
30930 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 if the N-th par
30940 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d ameter is.** nam
30950 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c eless, then NULL
30960 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e is returned. ^
30970 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
30980 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 ing is.** always
30990 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 in UTF-8 encodi
309a0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e ng even if the n
309b0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 amed parameter w
309c0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 as.** originally
309d0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 specified as UT
309e0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 F-16 in [sqlite3
309f0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a _prepare16()],.*
30a00 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
30a10 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b re16_v2()], or [
30a20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
30a30 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 6_v3()]..**.** S
30a40 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
30a50 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
30a60 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
30a70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
30a80 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
30a90 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
30aa0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
30ab0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f _index()]..*/.co
30ac0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
30ad0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
30ae0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
30af0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a mt*, int);../*.*
30b00 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 * CAPI3REF: Inde
30b10 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 x Of A Parameter
30b20 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 With A Given Na
30b30 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 me.** METHOD: sq
30b40 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
30b50 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 ^Return the ind
30b60 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 ex of an SQL par
30b70 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 ameter given its
30b80 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 name. ^The.**
30b90 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 index value retu
30ba0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 rned is suitable
30bb0 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 for use as the
30bc0 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 second.** parame
30bd0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
30be0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
30bf0 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 3_bind()]. ^A z
30c00 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e ero.** is return
30c10 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e ed if no matchin
30c20 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 g parameter is f
30c30 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 ound. ^The para
30c40 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 meter.** name mu
30c50 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 st be given in U
30c60 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 TF-8 even if the
30c70 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d original statem
30c80 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 ent.** was prepa
30c90 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 red from UTF-16
30ca0 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 text using [sqli
30cb0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
30cc0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
30cd0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 e3_prepare16_v3(
30ce0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c )]..**.** See al
30cf0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
30d00 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
30d10 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ind()],.** [sqli
30d20 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
30d30 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 er_count()], and
30d40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
30d50 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
30d60 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ()]..*/.int sqli
30d70 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
30d80 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 er_index(sqlite3
30d90 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 _stmt*, const ch
30da0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a ar *zName);../*.
30db0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
30dc0 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 et All Bindings
30dd0 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 On A Prepared St
30de0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f atement.** METHO
30df0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
30e00 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 **.** ^Contrary
30e10 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e to the intuition
30e20 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 of many, [sqlit
30e30 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 e3_reset()] does
30e40 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 not reset.** th
30e50 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
30e60 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d blob | bindings]
30e70 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 on a [prepared
30e80 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e statement]..** ^
30e90 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 Use this routine
30ea0 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f to reset all ho
30eb0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f st parameters to
30ec0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 NULL..*/.int sq
30ed0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 lite3_clear_bind
30ee0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d ings(sqlite3_stm
30ef0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
30f00 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 3REF: Number Of
30f10 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 Columns In A Res
30f20 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f ult Set.** METHO
30f30 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
30f40 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 **.** ^Return th
30f50 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
30f60 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c mns in the resul
30f70 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 t set returned b
30f80 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 y the.** [prepar
30f90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e ed statement]. ^
30fa0 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 If this routine
30fb0 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20 returns 0, that
30fc0 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 means the .** [p
30fd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
30fe0 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 t] returns no da
30ff0 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 ta (for example
31000 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a an [UPDATE])..**
31010 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 ^However, just
31020 62 65 63 61 75 73 65 20 74 68 69 73 20 72 6f 75 because this rou
31030 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 tine returns a p
31040 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64 ositive number d
31050 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 oes not.** mean
31060 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 that one or more
31070 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69 rows of data wi
31080 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 ll be returned.
31090 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 65 ^A SELECT state
310a0 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 ment.** will alw
310b0 61 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 74 ays have a posit
310c0 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ive sqlite3_colu
310d0 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64 mn_count() but d
310e0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a epending on the.
310f0 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 ** WHERE clause
31100 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 constraints and
31110 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e the table conten
31120 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 75 t, it might retu
31130 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a rn no rows..**.*
31140 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
31150 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
31160 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 )].*/.int sqlite
31170 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 3_column_count(s
31180 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
31190 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
311a0 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 3REF: Column Nam
311b0 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 es In A Result S
311c0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 et.** METHOD: sq
311d0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
311e0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
311f0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 return the name
31200 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 assigned to a p
31210 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e articular column
31220 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c .** in the resul
31230 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 t set of a [SELE
31240 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 CT] statement.
31250 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c ^The sqlite3_col
31260 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e umn_name().** in
31270 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
31280 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a a pointer to a z
31290 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
312a0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 TF-8 string.** a
312b0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
312c0 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 n_name16() retur
312d0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
312e0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
312f0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 d.** UTF-16 stri
31300 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 ng. ^The first
31310 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
31320 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
31330 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d ment].** that im
31340 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 plements the [SE
31350 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
31360 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 ^The second par
31370 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a ameter is the.**
31380 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 column number.
31390 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 ^The leftmost c
313a0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 olumn is number
313b0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 0..**.** ^The re
313c0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f turned string po
313d0 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 inter is valid u
313e0 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 ntil either the
313f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
31400 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 ent].** is destr
31410 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 oyed by [sqlite3
31420 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 _finalize()] or
31430 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d until the statem
31440 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ent is automatic
31450 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 ally.** reprepar
31460 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
31470 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
31480 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 _step()] for a p
31490 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a articular run.**
314a0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 or until the ne
314b0 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 xt call to.** sq
314c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
314d0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 e() or sqlite3_c
314e0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f olumn_name16() o
314f0 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d n the same colum
31500 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c n..**.** ^If sql
31510 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 ite3_malloc() fa
31520 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 ils during the p
31530 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 rocessing of eit
31540 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 her routine.** (
31550 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 for example duri
31560 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 ng a conversion
31570 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 from UTF-8 to UT
31580 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 F-16) then a.**
31590 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 NULL pointer is
315a0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
315b0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 ^The name of a r
315c0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 esult column is
315d0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 the value of the
315e0 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 "AS" clause for
315f0 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c .** that column,
31600 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 if there is an
31610 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 AS clause. If t
31620 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c here is no AS cl
31630 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ause.** then the
31640 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c name of the col
31650 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 umn is unspecifi
31660 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 ed and may chang
31670 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 e from.** one re
31680 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 lease of SQLite
31690 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a to the next..*/.
316a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
316b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
316c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
316d0 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 nt N);.const voi
316e0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
316f0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 n_name16(sqlite3
31700 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a _stmt*, int N);.
31710 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
31720 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 Source Of Data
31730 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c In A Query Resul
31740 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
31750 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
31760 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
31770 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 provide a means
31780 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 to determine the
31790 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
317a0 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 , and.** table c
317b0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 olumn that is th
317c0 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 e origin of a pa
317d0 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 rticular result
317e0 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 column in.** [SE
317f0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
31800 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 .** ^The name of
31810 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 the database or
31820 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e table or column
31830 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 can be returned
31840 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 as.** either a
31850 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 UTF-8 or UTF-16
31860 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 string. ^The _d
31870 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 atabase_ routine
31880 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 s return.** the
31890 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 database name, t
318a0 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 he _table_ routi
318b0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 nes return the t
318c0 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a able name, and.*
318d0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f * the origin_ ro
318e0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
318f0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a e column name..*
31900 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 * ^The returned
31910 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 string is valid
31920 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 until the [prepa
31930 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
31940 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 s destroyed.** u
31950 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
31960 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 nalize()] or unt
31970 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 il the statement
31980 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c is automaticall
31990 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 y.** reprepared
319a0 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c by the first cal
319b0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
319c0 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 ep()] for a part
319d0 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 icular run.** or
319e0 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 until the same
319f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 information is r
31a00 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 equested.** agai
31a10 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 n in a different
31a20 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a encoding..**.**
31a30 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 ^The names retu
31a40 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 rned are the ori
31a50 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 ginal un-aliased
31a60 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a names of the.**
31a70 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
31a80 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a , and column..**
31a90 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
31aa0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 rgument to these
31ab0 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 interfaces is a
31ac0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
31ad0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 ment]..** ^These
31ae0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
31af0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 n information ab
31b00 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 out the Nth resu
31b10 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e lt column return
31b20 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 ed by.** the sta
31b30 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 tement, where N
31b40 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 is the second fu
31b50 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e nction argument.
31b60 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f .** ^The left-mo
31b70 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c st column is col
31b80 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 umn 0 for these
31b90 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
31ba0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 ^If the Nth colu
31bb0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 mn returned by t
31bc0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
31bd0 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 an expression or
31be0 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 .** subquery and
31bf0 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e is not a column
31c00 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c value, then all
31c10 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 of these functi
31c20 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 ons return.** NU
31c30 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 LL. ^These rout
31c40 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 ine might also r
31c50 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 eturn NULL if a
31c60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
31c70 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 n error.** occur
31c80 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 s. ^Otherwise,
31c90 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 they return the
31ca0 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 name of the atta
31cb0 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 ched database, t
31cc0 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 able,.** or colu
31cd0 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 mn that query re
31ce0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 sult column was
31cf0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a extracted from..
31d00 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 **.** ^As with a
31d10 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ll other SQLite
31d20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 APIs, those whos
31d30 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 e names end with
31d40 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 "16" return.**
31d50 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 UTF-16 encoded s
31d60 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f trings and the o
31d70 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 ther functions r
31d80 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a eturn UTF-8..**.
31d90 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 ** ^These APIs a
31da0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c re only availabl
31db0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 e if the library
31dc0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 was compiled wi
31dd0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 th the.** [SQLIT
31de0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f E_ENABLE_COLUMN_
31df0 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 METADATA] C-prep
31e00 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e rocessor symbol.
31e10 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 .**.** If two or
31e20 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 more threads ca
31e30 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f ll one or more o
31e40 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
31e50 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d against the sam
31e60 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 e.** prepared st
31e70 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 atement and colu
31e80 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 mn at the same t
31e90 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 ime then the res
31ea0 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 ults are.** unde
31eb0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 fined..**.** If
31ec0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
31ed0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
31ee0 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 more.** [sqlite3
31ef0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
31f00 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d _name | column m
31f10 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 etadata interfac
31f20 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 es].** for the s
31f30 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 ame [prepared st
31f40 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 atement] and res
31f50 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 ult column.** at
31f60 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 the same time t
31f70 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 hen the results
31f80 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
31f90 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
31fa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 lite3_column_dat
31fb0 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 abase_name(sqlit
31fc0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 e3_stmt*,int);.c
31fd0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
31fe0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 e3_column_databa
31ff0 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 se_name16(sqlite
32000 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
32010 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
32020 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 3_column_table_n
32030 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
32040 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f *,int);.const vo
32050 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
32060 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 mn_table_name16(
32070 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
32080 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a t);.const char *
32090 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f sqlite3_column_o
320a0 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 rigin_name(sqlit
320b0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 e3_stmt*,int);.c
320c0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
320d0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e e3_column_origin
320e0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
320f0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a stmt*,int);../*.
32100 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 ** CAPI3REF: Dec
32110 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f lared Datatype O
32120 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 f A Query Result
32130 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
32140 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
32150 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d (The first param
32160 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 eter is a [prepa
32170 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
32180 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 ** If this state
32190 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 ment is a [SELEC
321a0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 T] statement and
321b0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
321c0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e of the.** return
321d0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 ed result set of
321e0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 that [SELECT] i
321f0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e s a table column
32200 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 (not an.** expr
32210 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
32220 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 ry) then the dec
32230 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 lared type of th
32240 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d e table.** colum
32250 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e n is returned.)^
32260 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f ^If the Nth co
32270 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 lumn of the resu
32280 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 lt set is an.**
32290 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 expression or su
322a0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e bquery, then a N
322b0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
322c0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 eturned..** ^The
322d0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
322e0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 is always UTF-8
322f0 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 encoded..**.**
32300 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 ^(For example, g
32310 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 iven the databas
32320 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 e schema:.**.**
32330 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 CREATE TABLE t1(
32340 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a c1 VARIANT);.**.
32350 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f ** and the follo
32360 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 wing statement t
32370 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a o be compiled:.*
32380 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b *.** SELECT c1 +
32390 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 1, c1 FROM t1;.
323a0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 **.** this routi
323b0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 ne would return
323c0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 the string "VARI
323d0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 ANT" for the sec
323e0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f ond result.** co
323f0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 lumn (i==1), and
32400 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
32410 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 for the first re
32420 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d sult column (i==
32430 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 0).)^.**.** ^SQL
32440 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
32450 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 run-time typing
32460 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 . ^So just beca
32470 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 use a column.**
32480 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 is declared to c
32490 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 ontain a particu
324a0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f lar type does no
324b0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a t mean that the.
324c0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 ** data stored i
324d0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 n that column is
324e0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 of the declared
324f0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 type. SQLite i
32500 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 s.** strongly ty
32510 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 ped, but the typ
32520 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e ing is dynamic n
32530 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 ot static. ^Typ
32540 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 e.** is associat
32550 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 ed with individu
32560 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 al values, not w
32570 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 ith the containe
32580 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f rs.** used to ho
32590 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e ld those values.
325a0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
325b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
325c0 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f ecltype(sqlite3_
325d0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
325e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
325f0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 column_decltype1
32600 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
32610 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
32620 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 I3REF: Evaluate
32630 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
32640 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
32650 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 te3_stmt.**.** A
32660 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 fter a [prepared
32670 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 statement] has
32680 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 been prepared us
32690 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 ing any of.** [s
326a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
326b0 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 2()], [sqlite3_p
326c0 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 repare_v3()], [s
326d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
326e0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 _v2()],.** or [s
326f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
32700 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 _v3()] or one of
32710 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 the legacy.** i
32720 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 nterfaces [sqlit
32730 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
32740 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
32750 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e e16()], this fun
32760 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 ction.** must be
32770 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d called one or m
32780 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 ore times to eva
32790 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d luate the statem
327a0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 ent..**.** The d
327b0 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 etails of the be
327c0 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 havior of the sq
327d0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 lite3_step() int
327e0 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a erface depend.**
327f0 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 on whether the
32800 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 statement was pr
32810 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 epared using the
32820 20 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74 65 newer "vX" inte
32830 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 rfaces.** [sqlit
32840 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d e3_prepare_v3()]
32850 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 , [sqlite3_prepa
32860 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 re_v2()], [sqlit
32870 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 e3_prepare16_v3(
32880 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
32890 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 prepare16_v2()]
328a0 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 or the older leg
328b0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 acy.** interface
328c0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 s [sqlite3_prepa
328d0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 re()] and [sqlit
328e0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e e3_prepare16()].
328f0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 The use of the
32900 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74 .** new "vX" int
32910 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d erface is recomm
32920 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 ended for new ap
32930 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 plications but t
32940 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 he legacy.** int
32950 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 erface will cont
32960 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f inue to be suppo
32970 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 rted..**.** ^In
32980 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 the legacy inter
32990 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e face, the return
329a0 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 value will be e
329b0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 ither [SQLITE_BU
329c0 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f SY],.** [SQLITE_
329d0 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 DONE], [SQLITE_R
329e0 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 OW], [SQLITE_ERR
329f0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OR], or [SQLITE_
32a00 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 MISUSE]..** ^Wit
32a10 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 h the "v2" inter
32a20 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 face, any of the
32a30 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 other [result c
32a40 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 odes] or.** [ext
32a50 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
32a60 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 es] might be ret
32a70 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a urned as well..*
32a80 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 *.** ^[SQLITE_BU
32a90 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 SY] means that t
32aa0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 he database engi
32ab0 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f ne was unable to
32ac0 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 acquire the.**
32ad0 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 database locks i
32ae0 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 t needs to do it
32af0 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 s job. ^If the
32b00 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b statement is a [
32b10 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 COMMIT].** or oc
32b20 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 curs outside of
32b30 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e an explicit tran
32b40 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f saction, then yo
32b50 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a u can retry the.
32b60 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 ** statement. I
32b70 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
32b80 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 is not a [COMMIT
32b90 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 ] and occurs wit
32ba0 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 hin an.** explic
32bb0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 it transaction t
32bc0 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 hen you should r
32bd0 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e ollback the tran
32be0 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a saction before.*
32bf0 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a * continuing..**
32c00 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e .** ^[SQLITE_DON
32c10 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 E] means that th
32c20 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 e statement has
32c30 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 finished executi
32c40 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c ng.** successful
32c50 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 ly. sqlite3_ste
32c60 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 p() should not b
32c70 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f e called again o
32c80 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a n this virtual.*
32c90 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 * machine withou
32ca0 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 t first calling
32cb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
32cc0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 ] to reset the v
32cd0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e irtual.** machin
32ce0 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e e back to its in
32cf0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a itial state..**.
32d00 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 ** ^If the SQL s
32d10 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 tatement being e
32d20 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 xecuted returns
32d30 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b any data, then [
32d40 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 SQLITE_ROW].** i
32d50 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 s returned each
32d60 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f time a new row o
32d70 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 f data is ready
32d80 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 for processing b
32d90 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e y the.** caller.
32da0 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 The values may
32db0 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e be accessed usin
32dc0 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 g the [column ac
32dd0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e cess functions].
32de0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 .** sqlite3_step
32df0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 () is called aga
32e00 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 in to retrieve t
32e10 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 he next row of d
32e20 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c ata..**.** ^[SQL
32e30 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 ITE_ERROR] means
32e40 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 that a run-time
32e50 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 error (such as
32e60 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 a constraint.**
32e70 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f violation) has o
32e80 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 ccurred. sqlite
32e90 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 3_step() should
32ea0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 not be called ag
32eb0 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d ain on.** the VM
32ec0 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 . More informati
32ed0 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 on may be found
32ee0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
32ef0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a te3_errmsg()]..*
32f00 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 * ^With the lega
32f10 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 cy interface, a
32f20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 more specific er
32f30 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 ror code (for ex
32f40 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 ample,.** [SQLIT
32f50 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 E_INTERRUPT], [S
32f60 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b QLITE_SCHEMA], [
32f70 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c SQLITE_CORRUPT],
32f80 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a and so forth).*
32f90 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 * can be obtaine
32fa0 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 d by calling [sq
32fb0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
32fc0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 n the.** [prepar
32fd0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 ed statement].
32fe0 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 ^In the "v2" int
32ff0 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d erface,.** the m
33000 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 ore specific err
33010 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 or code is retur
33020 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 ned directly by
33030 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a sqlite3_step()..
33040 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 **.** [SQLITE_MI
33050 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 SUSE] means that
33060 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e the this routin
33070 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 e was called ina
33080 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a ppropriately..**
33090 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 Perhaps it was
330a0 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 called on a [pre
330b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
330c0 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 that has.** alr
330d0 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 eady been [sqlit
330e0 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 e3_finalize | fi
330f0 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f nalized] or on o
33100 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 ne that had.** p
33110 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e reviously return
33120 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ed [SQLITE_ERROR
33130 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e ] or [SQLITE_DON
33140 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 E]. Or it could
33150 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 .** be the case
33160 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 that the same da
33170 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
33180 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 n is being used
33190 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 by two or.** mor
331a0 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 e threads at the
331b0 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 same moment in
331c0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 time..**.** For
331d0 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 all versions of
331e0 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 SQLite up to and
331f0 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 including 3.6.2
33200 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 3.1, a call to.*
33210 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
33220 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 ()] was required
33230 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 after sqlite3_s
33240 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 tep() returned a
33250 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 nything.** other
33260 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f than [SQLITE_RO
33270 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 W] before any su
33280 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 bsequent invocat
33290 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 ion of.** sqlite
332a0 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 3_step(). Failu
332b0 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 re to reset the
332c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
332d0 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 nt using .** [sq
332e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 lite3_reset()] w
332f0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 ould result in a
33300 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 n [SQLITE_MISUSE
33310 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a ] return from.**
33320 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e sqlite3_step().
33330 20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72 But after [ver
33340 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 sion 3.6.23.1] (
33350 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 [dateof:3.6.23.1
33360 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 ],.** sqlite3_st
33370 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 ep() began.** ca
33380 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 lling [sqlite3_r
33390 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 eset()] automati
333a0 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 cally in this ci
333b0 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 rcumstance rathe
333c0 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e r.** than return
333d0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 ing [SQLITE_MISU
333e0 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f SE]. This is no
333f0 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 t considered a c
33400 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 ompatibility.**
33410 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e break because an
33420 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 y application th
33430 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 at ever receives
33440 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 an SQLITE_MISUS
33450 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 E error.** is br
33460 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 oken by definiti
33470 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 on. The [SQLITE
33480 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d _OMIT_AUTORESET]
33490 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
334a0 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 tion.** can be u
334b0 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 sed to restore t
334c0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 he legacy behavi
334d0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f or..**.** <b>Goo
334e0 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 fy Interface Ale
334f0 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c rt:</b> In the l
33500 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c egacy interface,
33510 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 the sqlite3_ste
33520 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 p().** API alway
33530 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 s returns a gene
33540 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 ric error code,
33550 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 [SQLITE_ERROR],
33560 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a following any.**
33570 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 error other tha
33580 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 n [SQLITE_BUSY]
33590 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 and [SQLITE_MISU
335a0 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 SE]. You must c
335b0 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f all.** [sqlite3_
335c0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c reset()] or [sql
335d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
335e0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e in order to fin
335f0 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 d one of the.**
33600 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 specific [error
33610 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 codes] that bett
33620 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 er describes the
33630 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 error..** We ad
33640 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 mit that this is
33650 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e a goofy design.
33660 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 The problem ha
33670 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 s been fixed.**
33680 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e with the "v2" in
33690 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 terface. If you
336a0 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 prepare all of
336b0 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 your SQL stateme
336c0 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 nts.** using [sq
336d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 lite3_prepare_v3
336e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
336f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a prepare_v2()].**
33700 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
33710 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 pare16_v2()] or
33720 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
33730 31 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64 16_v3()] instead
33740 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 .** of the legac
33750 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 y [sqlite3_prepa
33760 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 re()] and [sqlit
33770 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 e3_prepare16()]
33780 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 interfaces,.** t
33790 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 hen the more spe
337a0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 cific [error cod
337b0 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 es] are returned
337c0 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 directly.** by
337d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 sqlite3_step().
337e0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 The use of the
337f0 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 20 "vX" interfaces
33800 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a is recommended..
33810 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 */.int sqlite3_s
33820 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 tep(sqlite3_stmt
33830 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
33840 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 REF: Number of c
33850 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 olumns in a resu
33860 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 lt set.** METHOD
33870 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
33880 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
33890 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 3_data_count(P)
338a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
338b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
338c0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a columns in the.*
338d0 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 * current row of
338e0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
338f0 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 of [prepared sta
33900 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 tement] P..** ^I
33910 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 f prepared state
33920 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 ment P does not
33930 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 have results rea
33940 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 dy to return.**
33950 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 (via calls to th
33960 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e [sqlite3_colum
33970 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f n_int | sqlite3_
33980 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a column_*()] of.*
33990 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 * interfaces) th
339a0 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f en sqlite3_data_
339b0 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 count(P) returns
339c0 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 0..** ^The sqli
339d0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 te3_data_count(P
339e0 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 ) routine also r
339f0 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 eturns 0 if P is
33a00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
33a10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
33a20 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 _data_count(P) r
33a30 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 outine returns 0
33a40 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 if the previous
33a50 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
33a60 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 ite3_step](P) re
33a70 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 turned [SQLITE_D
33a80 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 ONE]. ^The sqli
33a90 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 te3_data_count(P
33aa0 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e ).** will return
33ab0 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 non-zero if pre
33ac0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 vious call to [s
33ad0 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 qlite3_step](P)
33ae0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c returned.** [SQL
33af0 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 ITE_ROW], except
33b00 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 in the case of
33b10 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 the [PRAGMA incr
33b20 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a emental_vacuum].
33b30 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 ** where it alwa
33b40 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 ys returns zero
33b50 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 since each step
33b60 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 of that multi-st
33b70 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 ep.** pragma ret
33b80 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f urns 0 columns o
33b90 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 f data..**.** Se
33ba0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
33bb0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d _column_count()]
33bc0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
33bd0 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 data_count(sqlit
33be0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
33bf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
33c00 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 : Fundamental Da
33c10 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f tatypes.** KEYWO
33c20 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 RDS: SQLITE_TEXT
33c30 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 .**.** ^(Every v
33c40 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 alue in SQLite h
33c50 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 as one of five f
33c60 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 undamental datat
33c70 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ypes:.**.** <ul>
33c80 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 .** <li> 64-bit
33c90 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a signed integer.*
33ca0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 * <li> 64-bit IE
33cb0 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e EE floating poin
33cc0 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e t number.** <li>
33cd0 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 string.** <li>
33ce0 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c BLOB.** <li> NUL
33cf0 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a L.** </ul>)^.**.
33d00 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
33d10 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 ts are codes for
33d20 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 each of those t
33d30 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 ypes..**.** Note
33d40 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 that the SQLITE
33d50 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 _TEXT constant w
33d60 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 as also used in
33d70 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 SQLite version 2
33d80 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 .** for a comple
33d90 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d tely different m
33da0 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 eaning. Softwar
33db0 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 e that links aga
33dc0 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c inst both.** SQL
33dd0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e ite version 2 an
33de0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e d SQLite version
33df0 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 3 should use SQ
33e00 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a LITE3_TEXT, not.
33e10 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a ** SQLITE_TEXT..
33e20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
33e30 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 E_INTEGER 1.#de
33e40 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 fine SQLITE_FLOA
33e50 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 T 2.#define S
33e60 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 QLITE_BLOB 4
33e70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
33e80 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 NULL 5.#ifde
33e90 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 f SQLITE_TEXT.#
33ea0 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 undef SQLITE_TEX
33eb0 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 T.#else.# define
33ec0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 SQLITE_TEXT
33ed0 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 3.#endif.#defin
33ee0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 e SQLITE3_TEXT
33ef0 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3../*.** CAPI
33f00 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 3REF: Result Val
33f10 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 ues From A Query
33f20 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 .** KEYWORDS: {c
33f30 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e olumn access fun
33f40 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f ctions}.** METHO
33f50 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
33f60 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 **.** <b>Summary
33f70 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 :</b>.** <blockq
33f80 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64 uote><table bord
33f90 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 er=0 cellpadding
33fa0 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30 =0 cellspacing=0
33fb0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e >.** <tr><td><b>
33fc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
33fd0 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 lob</b><td>&rarr
33fe0 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74 ;<td>BLOB result
33ff0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 .** <tr><td><b>s
34000 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f qlite3_column_do
34010 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 uble</b><td>&rar
34020 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75 6c r;<td>REAL resul
34030 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e t.** <tr><td><b>
34040 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 sqlite3_column_i
34050 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b nt</b><td>→
34060 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45 47 <td>32-bit INTEG
34070 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 ER result.** <tr
34080 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f ><td><b>sqlite3_
34090 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e column_int64</b>
340a0 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34 <td>→<td>64
340b0 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73 -bit INTEGER res
340c0 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c ult.** <tr><td><
340d0 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e b>sqlite3_column
340e0 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 _text</b><td>&ra
340f0 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45 58 rr;<td>UTF-8 TEX
34100 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e T result.** <tr>
34110 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 <td><b>sqlite3_c
34120 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e olumn_text16</b>
34130 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 <td>→<td>UT
34140 46 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c 74 F-16 TEXT result
34150 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 .** <tr><td><b>s
34160 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
34170 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 lue</b><td>&rarr
34180 3b 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74 20 ;<td>The result
34190 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 as an .** [sqlit
341a0 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65 e3_value|unprote
341b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
341c0 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c ue] object..** <
341d0 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 tr><td> <td
341e0 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 > <td> 
341f0 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e ;.** <tr><td><b>
34200 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
34210 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 ytes</b><td>&rar
34220 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61 20 r;<td>Size of a
34230 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46 BLOB.** or a UTF
34240 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 20 69 -8 TEXT result i
34250 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c n bytes.** <tr><
34260 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f td><b>sqlite3_co
34270 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62 73 lumn_bytes16&nbs
34280 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 p; </b>.**
34290 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b <td>→
342a0 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f <td>Size o
342b0 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54 f UTF-16.** TEXT
342c0 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 in bytes.** <tr
342d0 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f ><td><b>sqlite3_
342e0 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c column_type</b><
342f0 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65 66 td>→<td>Def
34300 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70 65 ault.** datatype
34310 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a 2a of the result.*
34320 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63 * </table></bloc
34330 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 kquote>.**.** <b
34340 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a >Details:</b>.**
34350 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
34360 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 nes return infor
34370 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 mation about a s
34380 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 ingle column of
34390 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 the current.** r
343a0 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 esult row of a q
343b0 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 uery. ^In every
343c0 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 case the first
343d0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f argument is a po
343e0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 inter.** to the
343f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
34400 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 ent] that is bei
34410 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 ng evaluated (th
34420 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a e [sqlite3_stmt*
34430 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 ].** that was re
34440 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c turned from [sql
34450 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
34460 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 )] or one of its
34470 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e variants).** an
34480 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 d the second arg
34490 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 ument is the ind
344a0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e ex of the column
344b0 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 for which infor
344c0 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 mation.** should
344d0 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 be returned. ^T
344e0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 he leftmost colu
344f0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 mn of the result
34500 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 set has the ind
34510 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 ex 0..** ^The nu
34520 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
34530 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 in the result ca
34540 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 n be determined
34550 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
34560 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 3_column_count()
34570 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 ]..**.** If the
34580 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f SQL statement do
34590 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 es not currently
345a0 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 point to a vali
345b0 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 d row, or if the
345c0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 .** column index
345d0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
345e0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 , the result is
345f0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 undefined..** Th
34600 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 ese routines may
34610 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 only be called
34620 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 when the most re
34630 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 cent call to.**
34640 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
34650 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 has returned [S
34660 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e QLITE_ROW] and n
34670 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 either.** [sqlit
34680 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 e3_reset()] nor
34690 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
346a0 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 e()] have been c
346b0 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 alled subsequent
346c0 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 ly..** If any of
346d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
346e0 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 are called after
346f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
34700 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
34710 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 3_finalize()] or
34720 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f after [sqlite3_
34730 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 step()] has retu
34740 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e rned.** somethin
34750 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 g other than [SQ
34760 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 LITE_ROW], the r
34770 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 esults are undef
34780 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c ined..** If [sql
34790 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 ite3_step()] or
347a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
347b0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 ] or [sqlite3_fi
347c0 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 nalize()].** are
347d0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 called from a d
347e0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 ifferent thread
347f0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 while any of the
34800 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 se routines.** a
34810 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e re pending, then
34820 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
34830 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
34840 2a 20 54 68 65 20 66 69 72 73 74 20 73 69 78 20 * The first six
34850 69 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c 6f interfaces (_blo
34860 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74 b, _double, _int
34870 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c , _int64, _text,
34880 20 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a and _text16).**
34890 20 65 61 63 68 20 72 65 74 75 72 6e 20 74 68 65 each return the
348a0 20 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73 75 value of a resu
348b0 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73 lt column in a s
348c0 70 65 63 69 66 69 63 20 64 61 74 61 20 66 6f 72 pecific data for
348d0 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 mat. If.** the
348e0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 result column is
348f0 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20 69 not initially i
34900 6e 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 n the requested
34910 66 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61 6d format (for exam
34920 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71 ple,.** if the q
34930 75 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e 20 uery returns an
34940 69 6e 74 65 67 65 72 20 62 75 74 20 74 68 65 20 integer but the
34950 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
34960 65 78 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a ext() interface.
34970 2a 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65 78 ** is used to ex
34980 74 72 61 63 74 20 74 68 65 20 76 61 6c 75 65 29 tract the value)
34990 20 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74 then an automat
349a0 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 ic type conversi
349b0 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e on is performed.
349c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
349d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
349e0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
349f0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 s the.** [SQLITE
34a00 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 _INTEGER | datat
34a10 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 ype code] for th
34a20 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 e initial data t
34a30 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 ype.** of the re
34a40 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 sult column. ^T
34a50 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 he returned valu
34a60 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c e is one of [SQL
34a70 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a ITE_INTEGER],.**
34a80 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c [SQLITE_FLOAT],
34a90 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 [SQLITE_TEXT],
34aa0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f [SQLITE_BLOB], o
34ab0 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e r [SQLITE_NULL].
34ac0 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76 .** The return v
34ad0 61 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33 5f alue of sqlite3_
34ae0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63 61 column_type() ca
34af0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 63 n be used to dec
34b00 69 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20 ide which.** of
34b10 74 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e the first six in
34b20 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 62 terface should b
34b30 65 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63 e used to extrac
34b40 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c t the column val
34b50 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 ue..** The value
34b60 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
34b70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
34b80 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 () is only meani
34b90 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61 ngful if no.** a
34ba0 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f utomatic type co
34bb0 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f nversions have o
34bc0 63 63 75 72 72 65 64 20 66 6f 72 20 74 68 65 20 ccurred for the
34bd0 76 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69 6f value in questio
34be0 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61 20 n. .** After a
34bf0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c type conversion,
34c00 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 63 the result of c
34c10 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 alling sqlite3_c
34c20 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 olumn_type().**
34c30 69 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74 68 is undefined, th
34c40 6f 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20 20 ough harmless.
34c50 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f Future.** versio
34c60 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 ns of SQLite may
34c70 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 change the beha
34c80 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f vior of sqlite3_
34c90 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a column_type().**
34ca0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 following a typ
34cb0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a e conversion..**
34cc0 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c .** If the resul
34cd0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 61 t is a BLOB or a
34ce0 20 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74 68 TEXT string, th
34cf0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 en the sqlite3_c
34d00 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a olumn_bytes().**
34d10 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
34d20 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e 74 mn_bytes16() int
34d30 65 72 66 61 63 65 73 20 63 61 6e 20 62 65 20 75 erfaces can be u
34d40 73 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 sed to determine
34d50 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 the size.** of
34d60 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 that BLOB or str
34d70 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ing..**.** ^If t
34d80 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 he result is a B
34d90 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 LOB or UTF-8 str
34da0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c ing then the sql
34db0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
34dc0 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 s().** routine r
34dd0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
34de0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
34df0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e at BLOB or strin
34e00 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 g..** ^If the re
34e10 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 sult is a UTF-16
34e20 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 string, then sq
34e30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
34e40 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a es() converts.**
34e50 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 the string to U
34e60 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 TF-8 and then re
34e70 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
34e80 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 of bytes..** ^I
34e90 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
34ea0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 a numeric value
34eb0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
34ec0 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 umn_bytes() uses
34ed0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 .** [sqlite3_snp
34ee0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 rintf()] to conv
34ef0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 ert that value t
34f00 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 o a UTF-8 string
34f10 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 and returns.**
34f20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
34f30 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 tes in that stri
34f40 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 ng..** ^If the r
34f50 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 esult is NULL, t
34f60 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
34f70 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 mn_bytes() retur
34f80 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e ns zero..**.** ^
34f90 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
34fa0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 a BLOB or UTF-1
34fb0 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 6 string then th
34fc0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
34fd0 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f _bytes16().** ro
34fe0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
34ff0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
35000 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f s in that BLOB o
35010 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 r string..** ^If
35020 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
35030 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 UTF-8 string, t
35040 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
35050 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e mn_bytes16() con
35060 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 verts.** the str
35070 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e ing to UTF-16 an
35080 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 d then returns t
35090 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
350a0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 es..** ^If the r
350b0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 esult is a numer
350c0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 ic value then sq
350d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
350e0 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b es16() uses.** [
350f0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
35100 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 ()] to convert t
35110 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 hat value to a U
35120 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 TF-16 string and
35130 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 returns.** the
35140 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
35150 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a in that string..
35160 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
35170 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 t is NULL, then
35180 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
35190 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 ytes16() returns
351a0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 zero..**.** ^Th
351b0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 e values returne
351c0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f d by [sqlite3_co
351d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e lumn_bytes()] an
351e0 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 d .** [sqlite3_c
351f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d olumn_bytes16()]
35200 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 do not include
35210 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 the zero termina
35220 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a tors at the end.
35230 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 ** of the string
35240 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a . ^For clarity:
35250 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 the values retu
35260 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 rned by.** [sqli
35270 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
35280 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
35290 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
352a0 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 )] are the numbe
352b0 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e r of.** bytes in
352c0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 the string, not
352d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
352e0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a haracters..**.**
352f0 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e ^Strings return
35300 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
35310 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 lumn_text() and
35320 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
35330 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e ext16(),.** even
35340 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 empty strings,
35350 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d are always zero-
35360 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 terminated. ^Th
35370 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 e return.** valu
35380 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 e from sqlite3_c
35390 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 olumn_blob() for
353a0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 a zero-length B
353b0 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f LOB is a NULL po
353c0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e inter..**.** <b>
353d0 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 Warning:</b> ^Th
353e0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 e object returne
353f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f d by [sqlite3_co
35400 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 lumn_value()] is
35410 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 an.** [unprotec
35420 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
35430 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 e] object. In a
35440 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 multithreaded e
35450 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 nvironment,.** a
35460 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 n unprotected sq
35470 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
35480 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 ct may only be u
35490 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a sed safely with.
354a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
354b0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 _value()] and [s
354c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 qlite3_result_va
354d0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 lue()]..** If th
354e0 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 e [unprotected s
354f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
35500 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 ject returned by
35510 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
35520 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 umn_value()] is
35530 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 used in any othe
35540 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 r way, including
35550 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 calls.** to rou
35560 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 tines like [sqli
35570 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d te3_value_int()]
35580 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
35590 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 _text()],.** or
355a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
355b0 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 ytes()], the beh
355c0 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 avior is not thr
355d0 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63 eadsafe..** Henc
355e0 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 e, the sqlite3_c
355f0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e olumn_value() in
35600 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f terface.** is no
35610 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66 rmally only usef
35620 75 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69 6d ul within the im
35630 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
35640 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e .** [application
35650 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
35660 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74 ctions] or [virt
35670 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74 ual tables], not
35680 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c within.** top-l
35690 65 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e evel application
356a0 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 code..**.** The
356b0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
356c0 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 may attempt to c
356d0 6f 6e 76 65 72 74 20 74 68 65 20 64 61 74 61 74 onvert the datat
356e0 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ype of the resul
356f0 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70 t..** ^For examp
35700 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 le, if the inter
35710 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 nal representati
35720 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 on is FLOAT and
35730 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a a text result.**
35740 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b is requested, [
35750 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
35760 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 ()] is used inte
35770 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 rnally to perfor
35780 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 m the.** convers
35790 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ion automaticall
357a0 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 y. ^(The follow
357b0 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c ing table detail
357c0 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e s the conversion
357d0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 s.** that are ap
357e0 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c plied:.**.** <bl
357f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 ockquote>.** <ta
35800 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a ble border="1">.
35810 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 ** <tr><th> Inte
35820 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 rnal<br>Type <th
35830 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 > Requested<br>T
35840 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 ype <th> Conver
35850 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c sion.**.** <tr><
35860 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
35870 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e > INTEGER <td>
35880 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 Result is 0.**
35890 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
358a0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
358b0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
358c0 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 0.0.** <tr><td>
358d0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 NULL <td>
358e0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 TEXT <td> Res
358f0 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ult is a NULL po
35900 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 inter.** <tr><td
35910 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 > NULL <td>
35920 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 BLOB <td> R
35930 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 esult is a NULL
35940 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c pointer.** <tr><
35950 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
35960 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
35970 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e Convert from in
35980 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a teger to float.*
35990 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
359a0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 ER <td> TEXT
359b0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 <td> ASCII re
359c0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 ndering of the i
359d0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 nteger.** <tr><t
359e0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e d> INTEGER <td>
359f0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
35a00 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d Same as INTEGER-
35a10 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 >TEXT.** <tr><td
35a20 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
35a30 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b INTEGER <td> [
35a40 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 CAST] to INTEGER
35a50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c .** <tr><td> FL
35a60 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 OAT <td> TEX
35a70 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 T <td> ASCII
35a80 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
35a90 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 float.** <tr><t
35aa0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
35ab0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
35ac0 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a [CAST] to BLOB.*
35ad0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
35ae0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
35af0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 <td> [CAST] t
35b00 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 o INTEGER.** <tr
35b10 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c ><td> TEXT <
35b20 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
35b30 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 d> [CAST] to REA
35b40 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 L.** <tr><td> T
35b50 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c EXT <td> BL
35b60 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 OB <td> No ch
35b70 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ange.** <tr><td>
35b80 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 BLOB <td> I
35b90 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 NTEGER <td> [C
35ba0 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a AST] to INTEGER.
35bb0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f ** <tr><td> BLO
35bc0 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 B <td> FLOAT
35bd0 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 <td> [CAST]
35be0 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c to REAL.** <tr><
35bf0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 td> BLOB <td
35c00 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
35c10 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d Add a zero term
35c20 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 inator if needed
35c30 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 .** </table>.**
35c40 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a </blockquote>)^.
35c50 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
35c60 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 when type conver
35c70 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 sions occur, poi
35c80 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 nters returned b
35c90 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 y prior.** calls
35ca0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
35cb0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 mn_blob(), sqlit
35cc0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
35cd0 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 , and/or.** sqli
35ce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
35cf0 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 6() may be inval
35d00 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 idated..** Type
35d10 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 conversions and
35d20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 pointer invalida
35d30 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 tions might occu
35d40 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c r.** in the foll
35d50 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a owing cases:.**.
35d60 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
35d70 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 The initial cont
35d80 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e ent is a BLOB an
35d90 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
35da0 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 _text() or.**
35db0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d sqlite3_colum
35dc0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 n_text16() is ca
35dd0 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 lled. A zero-te
35de0 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a rminator might.*
35df0 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 * need to b
35e00 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 e added to the s
35e10 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c tring.</li>.** <
35e20 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 li> The initial
35e30 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 content is UTF-8
35e40 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 text and sqlite
35e50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
35e60 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
35e70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
35e80 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e t16() is called.
35e90 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 The content mu
35ea0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a st be converted.
35eb0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 ** to UTF-1
35ec0 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 6.</li>.** <li>
35ed0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 The initial cont
35ee0 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 ent is UTF-16 te
35ef0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 xt and sqlite3_c
35f00 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 olumn_bytes() or
35f10 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
35f20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 _column_text() i
35f30 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 s called. The c
35f40 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 ontent must be c
35f50 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 onverted.**
35f60 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a to UTF-8.</li>.
35f70 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e ** </ul>.**.** ^
35f80 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 Conversions betw
35f90 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 een UTF-16be and
35fa0 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c UTF-16le are al
35fb0 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 ways done in pla
35fc0 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 ce and do.** not
35fd0 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 invalidate a pr
35fe0 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f ior pointer, tho
35ff0 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 ugh of course th
36000 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
36010 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 buffer.** that
36020 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 the prior pointe
36030 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c r references wil
36040 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 l have been modi
36050 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e fied. Other kin
36060 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 ds.** of convers
36070 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 ion are done in
36080 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 place when it is
36090 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 possible, but s
360a0 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a ometimes they.**
360b0 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c are not possibl
360c0 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 e and in those c
360d0 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 ases prior point
360e0 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 ers are invalida
360f0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ted..**.** The s
36100 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 afest policy is
36110 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 to invoke these
36120 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f routines.** in o
36130 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
36140 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 ing ways:.**.**
36150 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c <ul>.** <li>sql
36160 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
36170 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 () followed by s
36180 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
36190 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c tes()</li>.** <
361a0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d li>sqlite3_colum
361b0 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 n_blob() followe
361c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
361d0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e umn_bytes()</li>
361e0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 .** <li>sqlite3
361f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
36200 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c followed by sql
36210 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
36220 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f s16()</li>.** </
36230 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 ul>.**.** In oth
36240 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 er words, you sh
36250 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 ould call sqlite
36260 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 3_column_text(),
36270 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
36280 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 mn_blob(), or sq
36290 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
362a0 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 t16() first to f
362b0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a orce the result.
362c0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 ** into the desi
362d0 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e red format, then
362e0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
362f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f column_bytes() o
36300 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c r.** sqlite3_col
36310 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f umn_bytes16() to
36320 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f find the size o
36330 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 f the result. D
36340 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a o not mix calls.
36350 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ** to sqlite3_co
36360 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 lumn_text() or s
36370 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
36380 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 ob() with calls
36390 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f to.** sqlite3_co
363a0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 lumn_bytes16(),
363b0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 and do not mix c
363c0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
363d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a column_text16().
363e0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f ** with calls to
363f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
36400 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e bytes()..**.** ^
36410 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 The pointers ret
36420 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 urned are valid
36430 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e until a type con
36440 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 version occurs a
36450 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 s.** described a
36460 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b bove, or until [
36470 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
36480 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 or [sqlite3_rese
36490 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 t()] or.** [sqli
364a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
364b0 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 is called. ^The
364c0 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 memory space us
364d0 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e ed to hold strin
364e0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 gs.** and BLOBs
364f0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 is freed automat
36500 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20 ically. Do not
36510 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 pass the pointer
36520 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 s returned.** fr
36530 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 om [sqlite3_colu
36540 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c mn_blob()], [sql
36550 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
36560 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a ()], etc. into.*
36570 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * [sqlite3_free(
36580 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 )]..**.** ^(If a
36590 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
365a0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 on error occurs
365b0 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 during the evalu
365c0 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 ation of any.**
365d0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
365e0 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c s, a default val
365f0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 ue is returned.
36600 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c The default val
36610 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 ue.** is either
36620 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 the integer 0, t
36630 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e he floating poin
36640 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 t number 0.0, or
36650 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 a NULL.** point
36660 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 er. Subsequent
36670 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
36680 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 3_errcode()] wil
36690 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c l return.** [SQL
366a0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f ITE_NOMEM].)^.*/
366b0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
366c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
366d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
366e0 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c int iCol);.doubl
366f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
36700 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
36710 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
36720 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f ;.int sqlite3_co
36730 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 lumn_int(sqlite3
36740 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
36750 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 );.sqlite3_int64
36760 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
36770 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 int64(sqlite3_st
36780 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
36790 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 const unsigned c
367a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
367b0 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 umn_text(sqlite3
367c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
367d0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
367e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
367f0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d xt16(sqlite3_stm
36800 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 t*, int iCol);.s
36810 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 qlite3_value *sq
36820 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
36830 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ue(sqlite3_stmt*
36840 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 , int iCol);.int
36850 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
36860 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 bytes(sqlite3_st
36870 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
36880 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
36890 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 mn_bytes16(sqlit
368a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
368b0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ol);.int sqlite3
368c0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c _column_type(sql
368d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
368e0 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 iCol);../*.** CA
368f0 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 PI3REF: Destroy
36900 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
36910 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 ment Object.** D
36920 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 ESTRUCTOR: sqlit
36930 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 e3_stmt.**.** ^T
36940 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c he sqlite3_final
36950 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 ize() function i
36960 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 s called to dele
36970 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 te a [prepared s
36980 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 tatement]..** ^I
36990 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
369a0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 t evaluation of
369b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e the statement en
369c0 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 countered no err
369d0 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 ors.** or if the
369e0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 statement is ne
369f0 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 ver been evaluat
36a00 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ed, then sqlite3
36a10 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 _finalize() retu
36a20 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b rns.** SQLITE_OK
36a30 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 . ^If the most
36a40 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f recent evaluatio
36a50 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 n of statement S
36a60 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a failed, then.**
36a70 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
36a80 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 e(S) returns the
36a90 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 appropriate [er
36aa0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 ror code] or.**
36ab0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
36ac0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 code]..**.** ^Th
36ad0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 e sqlite3_finali
36ae0 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 ze(S) routine ca
36af0 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 n be called at a
36b00 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a ny point during.
36b10 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c ** the life cycl
36b20 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 e of [prepared s
36b30 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 tatement] S:.**
36b40 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 before statement
36b50 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 S is ever evalu
36b60 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f ated, after.** o
36b70 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 ne or more calls
36b80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
36b90 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 et()], or after
36ba0 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b any call.** to [
36bb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
36bc0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 regardless of wh
36bd0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
36be0 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a statement has.*
36bf0 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 * completed exec
36c00 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e ution..**.** ^In
36c10 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 voking sqlite3_f
36c20 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e inalize() on a N
36c30 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 ULL pointer is a
36c40 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e harmless no-op.
36c50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 .**.** The appli
36c60 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 cation must fina
36c70 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 lize every [prep
36c80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
36c90 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 in order to avoi
36ca0 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 d.** resource le
36cb0 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 aks. It is a gr
36cc0 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 ievous error for
36cd0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
36ce0 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a to try to use.*
36cf0 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 * a prepared sta
36d00 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 tement after it
36d10 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a has been finaliz
36d20 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 ed. Any use of
36d30 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 a prepared.** st
36d40 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 atement after it
36d50 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 has been finali
36d60 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 zed can result i
36d70 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a n undefined and.
36d80 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 ** undesirable b
36d90 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 ehavior such as
36da0 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 segfaults and he
36db0 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a ap corruption..*
36dc0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 /.int sqlite3_fi
36dd0 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 nalize(sqlite3_s
36de0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
36df0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
36e00 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 set A Prepared S
36e10 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a tatement Object.
36e20 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
36e30 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 e3_stmt.**.** Th
36e40 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 e sqlite3_reset(
36e50 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 ) function is ca
36e60 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 lled to reset a
36e70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
36e80 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 ent].** object b
36e90 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 ack to its initi
36ea0 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 al state, ready
36eb0 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 to be re-execute
36ec0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 d..** ^Any SQL s
36ed0 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c tatement variabl
36ee0 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 es that had valu
36ef0 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d es bound to them
36f00 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 using.** the [s
36f10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
36f20 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f | sqlite3_bind_
36f30 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 *() API] retain
36f40 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a their values..**
36f50 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c Use [sqlite3_cl
36f60 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 ear_bindings()]
36f70 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e to reset the bin
36f80 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 dings..**.** ^Th
36f90 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 e [sqlite3_reset
36fa0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 (S)] interface r
36fb0 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 esets the [prepa
36fc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
36fd0 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 .** back to the
36fe0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 beginning of its
36ff0 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 program..**.**
37000 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ^If the most rec
37010 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ent call to [sql
37020 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f ite3_step(S)] fo
37030 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 r the.** [prepar
37040 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
37050 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
37060 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 _ROW] or [SQLITE
37070 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 _DONE],.** or if
37080 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
37090 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 )] has never bef
370a0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 ore been called
370b0 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 on S,.** then [s
370c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
370d0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
370e0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 _OK]..**.** ^If
370f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
37100 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
37110 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 _step(S)] for th
37120 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
37130 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 tatement] S indi
37140 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 cated an error,
37150 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 then.** [sqlite3
37160 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 _reset(S)] retur
37170 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 ns an appropriat
37180 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a e [error code]..
37190 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 **.** ^The [sqli
371a0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e te3_reset(S)] in
371b0 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 terface does not
371c0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 change the valu
371d0 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 es.** of any [sq
371e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
371f0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 bindings] on the
37200 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
37210 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 ment] S..*/.int
37220 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 sqlite3_reset(sq
37230 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
37240 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
37250 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 REF: Create Or R
37260 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 edefine SQL Func
37270 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 tions.** KEYWORD
37280 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 S: {function cre
37290 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a ation routines}.
372a0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 ** KEYWORDS: {ap
372b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
372c0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a d SQL function}.
372d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 ** KEYWORDS: {ap
372e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
372f0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d d SQL functions}
37300 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
37310 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 te3.**.** ^These
37320 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c functions (coll
37330 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 ectively known a
37340 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 s "function crea
37350 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a tion routines").
37360 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 ** are used to a
37370 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 dd SQL functions
37380 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f or aggregates o
37390 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 r to redefine th
373a0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 e behavior.** of
373b0 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 existing SQL fu
373c0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 nctions or aggre
373d0 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 gates. The only
373e0 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 differences bet
373f0 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f ween.** these ro
37400 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 utines are the t
37410 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 ext encoding exp
37420 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 ected for.** the
37430 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
37440 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 r (the name of t
37450 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e he function bein
37460 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e g created).** an
37470 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f d the presence o
37480 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 r absence of a d
37490 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 estructor callba
374a0 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 ck for.** the ap
374b0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 plication data p
374c0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ointer..**.** ^T
374d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
374e0 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 er is the [datab
374f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
37500 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c to which the SQL
37510 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 .** function is
37520 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 to be added. ^I
37530 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
37540 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 uses more than
37550 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 one database.**
37560 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 connection then
37570 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
37580 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
37590 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a s must be added.
375a0 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 ** to each datab
375b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 ase connection s
375c0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a eparately..**.**
375d0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 ^The second par
375e0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 ameter is the na
375f0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 me of the SQL fu
37600 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 nction to be cre
37610 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 ated or.** redef
37620 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 ined. ^The leng
37630 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 th of the name i
37640 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 s limited to 255
37650 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d bytes in a UTF-
37660 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 8.** representat
37670 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f ion, exclusive o
37680 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 f the zero-termi
37690 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 nator. ^Note th
376a0 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c at the name.** l
376b0 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 ength limit is i
376c0 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e n UTF-8 bytes, n
376d0 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f ot characters no
376e0 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 r UTF-16 bytes.
376f0 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 .** ^Any attemp
37700 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 t to create a fu
37710 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f nction with a lo
37720 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c nger name.** wil
37730 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c l result in [SQL
37740 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e ITE_MISUSE] bein
37750 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a g returned..**.*
37760 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 * ^The third par
37770 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a ameter (nArg).**
37780 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
37790 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 f arguments that
377a0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
377b0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 n or.** aggregat
377c0 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 e takes. ^If thi
377d0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d s parameter is -
377e0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 1, then the SQL
377f0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 function or.** a
37800 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b ggregate may tak
37810 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 e any number of
37820 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 arguments betwee
37830 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 n 0 and the limi
37840 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c t.** set by [sql
37850 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c ite3_limit]([SQL
37860 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 ITE_LIMIT_FUNCTI
37870 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 ON_ARG]). If th
37880 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d e third.** param
37890 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 eter is less tha
378a0 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 n -1 or greater
378b0 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 than 127 then th
378c0 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a e behavior is.**
378d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
378e0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 * ^The fourth pa
378f0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 rameter, eTextRe
37900 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 p, specifies wha
37910 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 t.** [SQLITE_UTF
37920 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 8 | text encodin
37930 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 g] this SQL func
37940 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 tion prefers for
37950 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 .** its paramete
37960 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 rs. The applica
37970 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 tion should set
37980 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 this parameter t
37990 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 o.** [SQLITE_UTF
379a0 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 16LE] if the fun
379b0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
379c0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a tion invokes .**
379d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
379e0 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 text16le()] on a
379f0 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c n input, or [SQL
37a00 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 ITE_UTF16BE] if
37a10 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
37a20 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 ation invokes [s
37a30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
37a40 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 t16be()] on an i
37a50 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c nput, or.** [SQL
37a60 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 ITE_UTF16] if [s
37a70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
37a80 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 t16()] is used,
37a90 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d or [SQLITE_UTF8]
37aa0 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 .** otherwise.
37ab0 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 ^The same SQL fu
37ac0 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 nction may be re
37ad0 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c gistered multipl
37ae0 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a e times using.**
37af0 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 different prefe
37b00 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
37b10 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 ngs, with differ
37b20 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ent implementati
37b30 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 ons for.** each
37b40 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 encoding..** ^Wh
37b50 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c en multiple impl
37b60 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 ementations of t
37b70 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e he same function
37b80 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 are available,
37b90 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 SQLite.** will p
37ba0 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 ick the one that
37bb0 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 involves the le
37bc0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 ast amount of da
37bd0 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a ta conversion..*
37be0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 *.** ^The fourth
37bf0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f parameter may o
37c00 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 ptionally be ORe
37c10 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 d with [SQLITE_D
37c20 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a ETERMINISTIC].**
37c30 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 to signal that
37c40 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c the function wil
37c50 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 l always return
37c60 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 the same result
37c70 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d given.** the sam
37c80 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 e inputs within
37c90 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 a single SQL sta
37ca0 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 tement. Most SQ
37cb0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a L functions are.
37cc0 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 ** deterministic
37cd0 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 . The built-in
37ce0 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 [random()] SQL f
37cf0 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 unction is an ex
37d00 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 ample of a.** fu
37d10 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e nction that is n
37d20 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 ot deterministic
37d30 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 . The SQLite qu
37d40 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 ery planner is a
37d50 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 ble to.** perfor
37d60 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 m additional opt
37d70 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 imizations on de
37d80 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 terministic func
37d90 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a tions, so use.**
37da0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f of the [SQLITE_
37db0 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 DETERMINISTIC] f
37dc0 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 lag is recommend
37dd0 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c ed where possibl
37de0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 e..**.** ^(The f
37df0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 ifth parameter i
37e00 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 s an arbitrary p
37e10 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 ointer. The imp
37e20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
37e30 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 he.** function c
37e40 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 an gain access t
37e50 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 o this pointer u
37e60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 sing [sqlite3_us
37e70 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a er_data()].)^.**
37e80 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 .** ^The sixth,
37e90 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 seventh and eigh
37ea0 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 th parameters, x
37eb0 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 Func, xStep and
37ec0 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 xFinal, are.** p
37ed0 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e ointers to C-lan
37ee0 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 guage functions
37ef0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 that implement t
37f00 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
37f10 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e or.** aggregate.
37f20 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 ^A scalar SQL f
37f30 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 unction requires
37f40 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 an implementati
37f50 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a on of the xFunc.
37f60 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 ** callback only
37f70 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 ; NULL pointers
37f80 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 must be passed a
37f90 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 s the xStep and
37fa0 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 xFinal.** parame
37fb0 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 ters. ^An aggreg
37fc0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ate SQL function
37fd0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 requires an imp
37fe0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 lementation of x
37ff0 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e Step.** and xFin
38000 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e al and NULL poin
38010 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 ter must be pass
38020 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 ed for xFunc. ^T
38030 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 o delete an exis
38040 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 ting.** SQL func
38050 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 tion or aggregat
38060 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 e, pass NULL poi
38070 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 nters for all th
38080 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ree function.**
38090 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a callbacks..**.**
380a0 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 ^(If the ninth
380b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
380c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
380d0 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 tion_v2() is not
380e0 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 NULL,.** then i
380f0 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 t is destructor
38100 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 for the applicat
38110 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 ion data pointer
38120 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 . .** The destru
38130 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 ctor is invoked
38140 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f when the functio
38150 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 n is deleted, ei
38160 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a ther by being.**
38170 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 overloaded or w
38180 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
38190 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 connection clos
381a0 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 es.)^.** ^The de
381b0 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f structor is also
381c0 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 invoked if the
381d0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 call to.** sqlit
381e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
381f0 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a on_v2() fails..*
38200 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 * ^When the dest
38210 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 ructor callback
38220 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 of the tenth par
38230 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 ameter is invoke
38240 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 d, it.** is pass
38250 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 ed a single argu
38260 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
38270 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c copy of the appl
38280 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a ication data .**
38290 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 pointer which w
382a0 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 as the fifth par
382b0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
382c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
382d0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 n_v2()..**.** ^I
382e0 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 t is permitted t
382f0 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 o register multi
38300 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ple implementati
38310 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a ons of the same.
38320 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 ** functions wit
38330 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 h the same name
38340 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 but with either
38350 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 differing number
38360 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 s of.** argument
38370 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 s or differing p
38380 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
38390 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 codings. ^SQLit
383a0 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 e will use.** th
383b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
383c0 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 that most close
383d0 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 ly matches the w
383e0 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a ay in which the.
383f0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ** SQL function
38400 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e is used. ^A fun
38410 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
38420 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d tion with a non-
38430 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 negative.** nArg
38440 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
38450 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 better match tha
38460 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 n a function imp
38470 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 lementation with
38480 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e .** a negative n
38490 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f Arg. ^A functio
384a0 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 n where the pref
384b0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 erred text encod
384c0 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 ing.** matches t
384d0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f he database enco
384e0 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 ding is a better
384f0 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 .** match than a
38500 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
38510 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 the encoding is
38520 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 different. .**
38530 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 ^A function wher
38540 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 e the encoding d
38550 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 ifference is bet
38560 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 ween UTF16le and
38570 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 UTF16be.** is a
38580 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 closer match th
38590 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 an a function wh
385a0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ere the encoding
385b0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a difference is.*
385c0 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 * between UTF8 a
385d0 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 nd UTF16..**.**
385e0 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 ^Built-in functi
385f0 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c ons may be overl
38600 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 oaded by new app
38610 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
38620 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a functions..**.*
38630 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f * ^An applicatio
38640 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
38650 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 on is permitted
38660 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a to call other.**
38670 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
38680 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 es. However, su
38690 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f ch calls must no
386a0 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 t.** close the d
386b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
386c0 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 on nor finalize
386d0 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 or reset the pre
386e0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
386f0 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 nt in which the
38700 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
38710 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ing..*/.int sqli
38720 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
38730 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ion(. sqlite3 *
38740 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 db,. const char
38750 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c *zFunctionName,
38760 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 . int nArg,. i
38770 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 nt eTextRep,. v
38780 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 oid *pApp,. voi
38790 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 d (*xFunc)(sqlit
387a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
387b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
387c0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65