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 20 3c 2f 75 C_WRITE]..** </u
ccc0: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
ccd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
cce0: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 TATE
ccf0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
cd00: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f ITE_FCNTL_GET_LO
cd10: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 CKPROXYFILE
cd20: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
cd30: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 TE_FCNTL_SET_LOC
cd40: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 KPROXYFILE
cd50: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 3.#define SQLIT
cd60: 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 E_FCNTL_LAST_ERR
cd70: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 NO
cd80: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
cd90: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 _FCNTL_SIZE_HINT
cda0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 5
cdb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
cdc0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 FCNTL_CHUNK_SIZE
cdd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 6.
cde0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
cdf0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 CNTL_FILE_POINTE
ce00: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 R 7.#
ce10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
ce20: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 NTL_SYNC_OMITTED
ce30: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 8.#d
ce40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
ce50: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 TL_WIN32_AV_RETR
ce60: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 Y 9.#de
ce70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
ce80: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 L_PERSIST_WAL
ce90: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 10.#def
cea0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
ceb0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 _OVERWRITE
cec0: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 11.#defi
ced0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
cee0: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 VFSNAME
cef0: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 12.#defin
cf00: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 e SQLITE_FCNTL_P
cf10: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
cf20: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 TE 13.#define
cf30: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 SQLITE_FCNTL_PR
cf40: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 AGMA
cf50: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 14.#define
cf60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 SQLITE_FCNTL_BUS
cf70: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 YHANDLER
cf80: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 15.#define S
cf90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 QLITE_FCNTL_TEMP
cfa0: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 FILENAME
cfb0: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 16.#define SQ
cfc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f LITE_FCNTL_MMAP_
cfd0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 SIZE
cfe0: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 18.#define SQL
cff0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 ITE_FCNTL_TRACE
d000: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
d010: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 19.#define SQLI
d020: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 TE_FCNTL_HAS_MOV
d030: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ED
d040: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 20.#define SQLIT
d050: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 E_FCNTL_SYNC
d060: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
d070: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
d080: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 _FCNTL_COMMIT_PH
d090: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 ASETWO 22
d0a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d0b0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f FCNTL_WIN32_SET_
d0c0: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a HANDLE 23.
d0d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
d0e0: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 CNTL_WAL_BLOCK
d0f0: 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 23 24.#
d100: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
d110: 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20 NTL_ZIPVFS
d120: 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 64 25.#d
d130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
d140: 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20 20 TL_RBU
d150: 20 20 20 20 20 20 20 20 20 20 32 36 0a 23 64 65 26.#de
d160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
d170: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 L_VFS_POINTER
d180: 20 20 20 20 20 20 20 20 20 32 37 0a 23 64 65 66 27.#def
d190: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
d1a0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 _JOURNAL_POINTER
d1b0: 20 20 20 20 20 20 20 20 32 38 0a 23 64 65 66 69 28.#defi
d1c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
d1d0: 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 WIN32_GET_HANDLE
d1e0: 20 20 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e 29.#defin
d1f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 e SQLITE_FCNTL_P
d200: 44 42 20 20 20 20 20 20 20 20 20 20 20 20 20 20 DB
d210: 20 20 20 20 20 20 33 30 0a 23 64 65 66 69 6e 65 30.#define
d220: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 SQLITE_FCNTL_BE
d230: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 GIN_ATOMIC_WRITE
d240: 20 20 20 20 20 33 31 0a 23 64 65 66 69 6e 65 20 31.#define
d250: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d SQLITE_FCNTL_COM
d260: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 MIT_ATOMIC_WRITE
d270: 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 32.#define S
d280: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c QLITE_FCNTL_ROLL
d290: 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 BACK_ATOMIC_WRIT
d2a0: 45 20 20 33 33 0a 0a 2f 2a 20 64 65 70 72 65 63 E 33../* deprec
d2b0: 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 ated names */.#d
d2c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 efine SQLITE_GET
d2d0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 _LOCKPROXYFILE
d2e0: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c SQLITE_FCNTL
d2f0: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 _GET_LOCKPROXYFI
d300: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 LE.#define SQLIT
d310: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 E_SET_LOCKPROXYF
d320: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f ILE SQLITE_
d330: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 FCNTL_SET_LOCKPR
d340: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 OXYFILE.#define
d350: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e SQLITE_LAST_ERRN
d360: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51 O SQ
d370: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f LITE_FCNTL_LAST_
d380: 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 ERRNO.../*.** CA
d390: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 PI3REF: Mutex Ha
d3a0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d ndle.**.** The m
d3b0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 utex module with
d3c0: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 in SQLite define
d3d0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 s [sqlite3_mutex
d3e0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 ] to be an.** ab
d3f0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 stract type for
d400: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 a mutex object.
d410: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
d420: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 never looks.**
d430: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 at the internal
d440: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f representation o
d450: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 f an [sqlite3_mu
d460: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a tex]. It only.*
d470: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 * deals with poi
d480: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 nters to the [sq
d490: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a lite3_mutex] obj
d4a0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 ect..**.** Mutex
d4b0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 es are created u
d4c0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 sing [sqlite3_mu
d4d0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f tex_alloc()]..*/
d4e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
d4f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 sqlite3_mutex sq
d500: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a lite3_mutex;../*
d510: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f .** CAPI3REF: Lo
d520: 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e adable Extension
d530: 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 Thunk.**.** A p
d540: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70 ointer to the op
d550: 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69 aque sqlite3_api
d560: 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74 _routines struct
d570: 75 72 65 20 69 73 20 70 61 73 73 65 64 20 61 73 ure is passed as
d580: 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 .** the third pa
d590: 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79 rameter to entry
d5a0: 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 points of [load
d5b0: 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d able extensions]
d5c0: 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63 . This.** struc
d5d0: 74 75 72 65 20 6d 75 73 74 20 62 65 20 74 79 70 ture must be typ
d5e0: 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20 edefed in order
d5f0: 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63 to work around c
d600: 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 ompiler warnings
d610: 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 .** on some plat
d620: 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 forms..*/.typede
d630: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
d640: 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71 _api_routines sq
d650: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e lite3_api_routin
d660: 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 es;../*.** CAPI3
d670: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
d680: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 e Object.**.** A
d690: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
d6a0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 e sqlite3_vfs ob
d6b0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 ject defines the
d6c0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 interface betwe
d6d0: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 en.** the SQLite
d6e0: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e core and the un
d6f0: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 derlying operati
d700: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 ng system. The
d710: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 "vfs".** in the
d720: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 name of the obje
d730: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 ct stands for "v
d740: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 irtual file syst
d750: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 em". See.** the
d760: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 [VFS | VFS docu
d770: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 mentation] for f
d780: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 urther informati
d790: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 56 46 on..**.** The VF
d7a0: 53 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 S interface is s
d7b0: 6f 6d 65 74 69 6d 65 73 20 65 78 74 65 6e 64 65 ometimes extende
d7c0: 64 20 62 79 20 61 64 64 69 6e 67 20 6e 65 77 20 d by adding new
d7d0: 6d 65 74 68 6f 64 73 20 6f 6e 74 6f 0a 2a 2a 20 methods onto.**
d7e0: 74 68 65 20 65 6e 64 2e 20 20 45 61 63 68 20 74 the end. Each t
d7f0: 69 6d 65 20 73 75 63 68 20 61 6e 20 65 78 74 65 ime such an exte
d800: 6e 73 69 6f 6e 20 6f 63 63 75 72 73 2c 20 74 68 nsion occurs, th
d810: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 e iVersion field
d820: 0a 2a 2a 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 .** is increment
d830: 65 64 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f ed. The iVersio
d840: 6e 20 76 61 6c 75 65 20 73 74 61 72 74 65 64 20 n value started
d850: 6f 75 74 20 61 73 20 31 20 69 6e 0a 2a 2a 20 53 out as 1 in.** S
d860: 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 QLite [version 3
d870: 2e 35 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 .5.0] on [dateof
d880: 3a 33 2e 35 2e 30 5d 2c 20 74 68 65 6e 20 69 6e :3.5.0], then in
d890: 63 72 65 61 73 65 64 20 74 6f 20 32 0a 2a 2a 20 creased to 2.**
d8a0: 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72 with SQLite [ver
d8b0: 73 69 6f 6e 20 33 2e 37 2e 30 5d 20 6f 6e 20 5b sion 3.7.0] on [
d8c0: 64 61 74 65 6f 66 3a 33 2e 37 2e 30 5d 2c 20 61 dateof:3.7.0], a
d8d0: 6e 64 20 74 68 65 6e 20 69 6e 63 72 65 61 73 65 nd then increase
d8e0: 64 0a 2a 2a 20 74 6f 20 33 20 77 69 74 68 20 53 d.** to 3 with S
d8f0: 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 QLite [version 3
d900: 2e 37 2e 36 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 .7.6] on [dateof
d910: 3a 33 2e 37 2e 36 5d 2e 20 20 41 64 64 69 74 69 :3.7.6]. Additi
d920: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 6d onal fields.** m
d930: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 ay be appended t
d940: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 o the sqlite3_vf
d950: 73 20 6f 62 6a 65 63 74 20 61 6e 64 20 74 68 65 s object and the
d960: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 0a iVersion value.
d970: 2a 2a 20 6d 61 79 20 69 6e 63 72 65 61 73 65 20 ** may increase
d980: 61 67 61 69 6e 20 69 6e 20 66 75 74 75 72 65 20 again in future
d990: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
d9a0: 74 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 te..** Note that
d9b0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a the structure.*
d9c0: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 * of the sqlite3
d9d0: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e _vfs object chan
d9e0: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 ges in the trans
d9f0: 69 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 53 51 ition from.** SQ
da00: 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e Lite [version 3.
da10: 35 2e 39 5d 20 74 6f 20 5b 76 65 72 73 69 6f 6e 5.9] to [version
da20: 20 33 2e 36 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 3.6.0] on [date
da30: 6f 66 3a 33 2e 36 2e 30 5d 0a 2a 2a 20 61 6e 64 of:3.6.0].** and
da40: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f yet the iVersio
da50: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 20 n field was not
da60: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 modified..**.**
da70: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 The szOsFile fie
da80: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f ld is the size o
da90: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 f the subclassed
daa0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a [sqlite3_file].
dab0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 ** structure use
dac0: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 d by this VFS.
dad0: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 mxPathname is th
dae0: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 e maximum length
daf0: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d of.** a pathnam
db00: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a e in this VFS..*
db10: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 *.** Registered
db20: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 sqlite3_vfs obje
db30: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 cts are kept on
db40: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f a linked list fo
db50: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 rmed by.** the p
db60: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 Next pointer. T
db70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f he [sqlite3_vfs_
db80: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 register()].** a
db90: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f nd [sqlite3_vfs_
dba0: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e unregister()] in
dbb0: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 terfaces manage
dbc0: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 this list.** in
dbd0: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 a thread-safe wa
dbe0: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 y. The [sqlite3
dbf0: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 _vfs_find()] int
dc00: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 erface.** search
dc10: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 es the list. Ne
dc20: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 ither the applic
dc30: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 ation code nor t
dc40: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d he VFS.** implem
dc50: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 entation should
dc60: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f use the pNext po
dc70: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 inter..**.** The
dc80: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 pNext field is
dc90: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 the only field i
dca0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 n the sqlite3_vf
dcb0: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 s.** structure t
dcc0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 hat SQLite will
dcd0: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 ever modify. SQ
dce0: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 Lite will only a
dcf0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 ccess.** or modi
dd00: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 fy this field wh
dd10: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 ile holding a pa
dd20: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 rticular static
dd30: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 mutex..** The ap
dd40: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
dd50: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e never modify an
dd60: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 ything within th
dd70: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a e sqlite3_vfs.**
dd80: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 object once the
dd90: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e object has been
dda0: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a registered..**.
ddb0: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 ** The zName fie
ddc0: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d ld holds the nam
ddd0: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 e of the VFS mod
dde0: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d ule. The name m
ddf0: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 ust.** be unique
de00: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 across all VFS
de10: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b modules..**.** [
de20: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
de30: 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 en]].** ^SQLite
de40: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 guarantees that
de50: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 the zFilename pa
de60: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e rameter to xOpen
de70: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 .** is either a
de80: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 NULL pointer or
de90: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a string obtained.
dea0: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 ** from xFullPat
deb0: 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 hname() with an
dec0: 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 optional suffix
ded0: 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 added..** ^If a
dee0: 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 suffix is added
def0: 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 to the zFilename
df00: 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 parameter, it w
df10: 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f ill.** consist o
df20: 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 f a single "-" c
df30: 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 haracter followe
df40: 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 d by no more tha
df50: 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d n.** 11 alphanum
df60: 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 eric and/or "-"
df70: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e characters..** ^
df80: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 SQLite further g
df90: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a uarantees that.*
dfa0: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c * the string wil
dfb0: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 l be valid and u
dfc0: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 nchanged until x
dfd0: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 Close() is.** ca
dfe0: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 lled. Because of
dff0: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 the previous se
e000: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b ntence,.** the [
e010: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 sqlite3_file] ca
e020: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 n safely store a
e030: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a pointer to the.
e040: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 ** filename if i
e050: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d t needs to remem
e060: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 ber the filename
e070: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e for some reason
e080: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c ..** If the zFil
e090: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 ename parameter
e0a0: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 to xOpen is a NU
e0b0: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
e0c0: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e xOpen.** must in
e0d0: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d vent its own tem
e0e0: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 porary name for
e0f0: 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e the file. ^When
e100: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 ever the .** xFi
e110: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
e120: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c is NULL it will
e130: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 also be the cas
e140: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c e that the.** fl
e150: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 ags parameter wi
e160: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 ll include [SQLI
e170: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
e180: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 CLOSE]..**.** Th
e190: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
e1a0: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c to xOpen() incl
e1b0: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 udes all bits se
e1c0: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 t in.** the flag
e1d0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 s argument to [s
e1e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
e1f0: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 ]. Or if [sqlit
e200: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 e3_open()].** or
e210: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
e220: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 ()] is used, the
e230: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 n flags includes
e240: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 at least.** [SQ
e250: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
e260: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f ITE] | [SQLITE_O
e270: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a PEN_CREATE]. .**
e280: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e If xOpen() open
e290: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e s a file read-on
e2a0: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 ly then it sets
e2b0: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a *pOutFlags to.**
e2c0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 include [SQLITE
e2d0: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e _OPEN_READONLY].
e2e0: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 Other bits in
e2f0: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 *pOutFlags may b
e300: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 e set..**.** ^(S
e310: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 QLite will also
e320: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 add one of the f
e330: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 ollowing flags t
e340: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a o the xOpen().**
e350: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 call, depending
e360: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 on the object b
e370: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a eing opened:.**.
e380: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
e390: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
e3a0: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 IN_DB].** <li>
e3b0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 [SQLITE_OPEN_MAI
e3c0: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c N_JOURNAL].** <l
e3d0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
e3e0: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 _TEMP_DB].** <li
e3f0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
e400: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a TEMP_JOURNAL].**
e410: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
e420: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 PEN_TRANSIENT_DB
e430: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
e440: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e TE_OPEN_SUBJOURN
e450: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
e460: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 LITE_OPEN_MASTER
e470: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 _JOURNAL].** <li
e480: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
e490: 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a WAL].** </ul>)^.
e4a0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 **.** The file I
e4b0: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f /O implementatio
e4c0: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 n can use the ob
e4d0: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 ject type flags
e4e0: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 to.** change the
e4f0: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 way it deals wi
e500: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 th files. For e
e510: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 xample, an appli
e520: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 cation.** that d
e530: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f oes not care abo
e540: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 ut crash recover
e550: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 y or rollback mi
e560: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 ght make.** the
e570: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 open of a journa
e580: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 l file a no-op.
e590: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 Writes to this
e5a0: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a journal would.**
e5b0: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c also be no-ops,
e5c0: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 and any attempt
e5d0: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 to read the jou
e5e0: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 rnal would retur
e5f0: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 n.** SQLITE_IOER
e600: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 R. Or the imple
e610: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 mentation might
e620: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 recognize that a
e630: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c database.** fil
e640: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 e will be doing
e650: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 page-aligned sec
e660: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 tor reads and wr
e670: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d ites in a random
e680: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 .** order and se
e690: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 t up its I/O sub
e6a0: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 system according
e6b0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ly..**.** SQLite
e6c0: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 might also add
e6d0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
e6e0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 wing flags to th
e6f0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a e xOpen method:.
e700: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
e710: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f i> [SQLITE_OPEN_
e720: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a DELETEONCLOSE].*
e730: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f * <li> [SQLITE_O
e740: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a PEN_EXCLUSIVE].*
e750: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 * </ul>.**.** Th
e760: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 e [SQLITE_OPEN_D
e770: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c ELETEONCLOSE] fl
e780: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c ag means the fil
e790: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 e should be.** d
e7a0: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 eleted when it i
e7b0: 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 s closed. ^The
e7c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c [SQLITE_OPEN_DEL
e7d0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 ETEONCLOSE].** w
e7e0: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 ill be set for T
e7f0: 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e EMP databases an
e800: 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 d their journals
e810: 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 , transient.** d
e820: 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 atabases, and su
e830: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a bjournals..**.**
e840: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 ^The [SQLITE_OP
e850: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c EN_EXCLUSIVE] fl
e860: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 ag is always use
e870: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e d in conjunction
e880: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 .** with the [SQ
e890: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
e8a0: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 ] flag, which ar
e8b0: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a e both directly.
e8c0: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 ** analogous to
e8d0: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f the O_EXCL and O
e8e0: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 _CREAT flags of
e8f0: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 the POSIX open()
e900: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 .** API. The SQ
e910: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 LITE_OPEN_EXCLUS
e920: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 IVE flag, when p
e930: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a aired with the .
e940: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 ** SQLITE_OPEN_C
e950: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 REATE, is used t
e960: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 o indicate that
e970: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 file should alwa
e980: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 ys.** be created
e990: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 , and that it is
e9a0: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 an error if it
e9b0: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a already exists..
e9c0: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c ** It is <i>not<
e9d0: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 /i> used to indi
e9e0: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 cate the file sh
e9f0: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a ould be opened .
ea00: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 ** for exclusive
ea10: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e access..**.** ^
ea20: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c At least szOsFil
ea30: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 e bytes of memor
ea40: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 y are allocated
ea50: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 by SQLite.** to
ea60: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 hold the [sqlit
ea70: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 e3_file] structu
ea80: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 re passed as the
ea90: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 third.** argume
eaa0: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 nt to xOpen. Th
eab0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 e xOpen method d
eac0: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a oes not have to.
ead0: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 ** allocate the
eae0: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 structure; it sh
eaf0: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 ould just fill i
eb00: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 t in. Note that
eb10: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 .** the xOpen me
eb20: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 thod must set th
eb30: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 e sqlite3_file.p
eb40: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 Methods to eithe
eb50: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 r.** a valid [sq
eb60: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
eb70: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e ] object or to N
eb80: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 ULL. xOpen must
eb90: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e do.** this even
eba0: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 if the open fai
ebb0: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 ls. SQLite expe
ebc0: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c cts that the sql
ebd0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
ebe0: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 ds.** element wi
ebf0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 ll be valid afte
ec00: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 r xOpen returns
ec10: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 regardless of th
ec20: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 e success.** or
ec30: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 failure of the x
ec40: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a Open call..**.**
ec50: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 [[sqlite3_vfs.x
ec60: 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 Access]].** ^The
ec70: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
ec80: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 to xAccess() may
ec90: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 be [SQLITE_ACCE
eca0: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f SS_EXISTS].** to
ecb0: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 test for the ex
ecc0: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c istence of a fil
ecd0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 e, or [SQLITE_AC
ece0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 CESS_READWRITE]
ecf0: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 to.** test wheth
ed00: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 er a file is rea
ed10: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 dable and writab
ed20: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 le, or [SQLITE_A
ed30: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 CCESS_READ].** t
ed40: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 o test whether a
ed50: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 file is at leas
ed60: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 t readable. Th
ed70: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a e file can be a.
ed80: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a ** directory..**
ed90: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
eda0: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 always allocate
edb0: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 at least mxPath
edc0: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 name+1 bytes for
edd0: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 the.** output b
ede0: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e uffer xFullPathn
edf0: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 ame. The exact
ee00: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 size of the outp
ee10: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 ut buffer.** is
ee20: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 also passed as a
ee30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f parameter to bo
ee40: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 th methods. If
ee50: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 the output buffe
ee60: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 r.** is not larg
ee70: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 e enough, [SQLIT
ee80: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 E_CANTOPEN] shou
ee90: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 ld be returned.
eea0: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a Since this is.**
eeb0: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 handled as a fa
eec0: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c tal error by SQL
eed0: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 ite, vfs impleme
eee0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ntations should
eef0: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 endeavor.** to p
ef00: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 revent this by s
ef10: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d etting mxPathnam
ef20: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e e to a sufficien
ef30: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e tly large value.
ef40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 .**.** The xRand
ef50: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 omness(), xSleep
ef60: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 (), xCurrentTime
ef70: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 (), and xCurrent
ef80: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 TimeInt64().** i
ef90: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f nterfaces are no
efa0: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 t strictly a par
efb0: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 t of the filesys
efc0: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 tem, but they ar
efd0: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e e.** included in
efe0: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 the VFS structu
eff0: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e re for completen
f000: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e ess..** The xRan
f010: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 domness() functi
f020: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 on attempts to r
f030: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 eturn nBytes byt
f040: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 es.** of good-qu
f050: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 ality randomness
f060: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 into zOut. The
f070: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 return value is
f080: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e .** the actual n
f090: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f umber of bytes o
f0a0: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 f randomness obt
f0b0: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 ained..** The xS
f0c0: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 leep() method ca
f0d0: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 uses the calling
f0e0: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 thread to sleep
f0f0: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 for at.** least
f100: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d the number of m
f110: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 icroseconds give
f120: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e n. ^The xCurren
f130: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f tTime().** metho
f140: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 d returns a Juli
f150: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f an Day Number fo
f160: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 r the current da
f170: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a te and time as.*
f180: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 * a floating poi
f190: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 nt value..** ^Th
f1a0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e e xCurrentTimeIn
f1b0: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 t64() method ret
f1c0: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 urns, as an inte
f1d0: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a ger, the Julian.
f1e0: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 ** Day Number mu
f1f0: 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 ltiplied by 8640
f200: 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 0000 (the number
f210: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 of milliseconds
f220: 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 in .** a 24-hou
f230: 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 r day). .** ^SQ
f240: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 Lite will use th
f250: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e e xCurrentTimeIn
f260: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 t64() method to
f270: 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a get the current.
f280: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 ** date and time
f290: 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 if that method
f2a0: 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 is available (if
f2b0: 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f iVersion is 2 o
f2c0: 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e r .** greater an
f2d0: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 d the function p
f2e0: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ointer is not NU
f2f0: 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c LL) and will fal
f300: 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 l back.** to xCu
f310: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 rrentTime() if x
f320: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 CurrentTimeInt64
f330: 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c () is unavailabl
f340: 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 e..**.** ^The xS
f350: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 etSystemCall(),
f360: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 xGetSystemCall()
f370: 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 , and xNestSyste
f380: 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 mCall() interfac
f390: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 es.** are not us
f3a0: 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 ed by the SQLite
f3b0: 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 core. These op
f3c0: 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 tional interface
f3d0: 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a s are provided.*
f3e0: 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 * by some VFSes
f3f0: 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 to facilitate te
f400: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 sting of the VFS
f410: 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 code. By overri
f420: 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 ding .** system
f430: 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 calls with funct
f440: 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 ions under its c
f450: 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 ontrol, a test p
f460: 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 rogram can.** si
f470: 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e mulate faults an
f480: 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f d error conditio
f490: 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 ns that would ot
f4a0: 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69 herwise be diffi
f4b0: 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 cult.** or impos
f4c0: 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e sible to induce.
f4d0: 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 The set of sys
f4e0: 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 tem calls that c
f4f0: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e an be overridden
f500: 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 .** varies from
f510: 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 one VFS to anoth
f520: 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 er, and from one
f530: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 version of the
f540: 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a same VFS to the.
f550: 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 ** next. Applic
f560: 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 ations that use
f570: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
f580: 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65 must be prepare
f590: 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 d for any.** or
f5a0: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 all of these int
f5b0: 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 erfaces to be NU
f5c0: 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 LL or for their
f5d0: 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e behavior to chan
f5e0: 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 ge.** from one r
f5f0: 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 elease to the ne
f600: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e xt. Application
f610: 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d s must not attem
f620: 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 pt to access.**
f630: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 any of these met
f640: 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72 hods if the iVer
f650: 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 sion of the VFS
f660: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a is less than 3..
f670: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
f680: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 t sqlite3_vfs sq
f690: 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 lite3_vfs;.typed
f6a0: 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 ef void (*sqlite
f6b0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 3_syscall_ptr)(v
f6c0: 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c oid);.struct sql
f6d0: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 ite3_vfs {. int
f6e0: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 iVersion;
f6f0: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 /* Structu
f700: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 re version numbe
f710: 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 r (currently 3)
f720: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c */. int szOsFil
f730: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a e; /*
f740: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 Size of subclas
f750: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 sed sqlite3_file
f760: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 */. int mxPath
f770: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f name; /
f780: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 * Maximum file p
f790: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a athname length *
f7a0: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 /. sqlite3_vfs
f7b0: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 *pNext; /*
f7c0: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 Next registered
f7d0: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 VFS */. const c
f7e0: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 har *zName;
f7f0: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 /* Name of thi
f800: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 s virtual file s
f810: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 ystem */. void
f820: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 *pAppData;
f830: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 /* Pointer t
f840: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 o application-sp
f850: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 ecific data */.
f860: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 int (*xOpen)(sq
f870: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
f880: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 t char *zName, s
f890: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 qlite3_file*,.
f8a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 int
f8b0: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 flags, int *pOu
f8c0: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 tFlags);. int (
f8d0: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 *xDelete)(sqlite
f8e0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
f8f0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 ar *zName, int s
f900: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 yncDir);. int (
f910: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 *xAccess)(sqlite
f920: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
f930: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 ar *zName, int f
f940: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f lags, int *pResO
f950: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 ut);. int (*xFu
f960: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 llPathname)(sqli
f970: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
f980: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 char *zName, int
f990: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 nOut, char *zOu
f9a0: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 t);. void *(*xD
f9b0: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 lOpen)(sqlite3_v
f9c0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
f9d0: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 *zFilename);. v
f9e0: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 oid (*xDlError)(
f9f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
fa00: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a t nByte, char *z
fa10: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 ErrMsg);. void
fa20: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 (*(*xDlSym)(sqli
fa30: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 te3_vfs*,void*,
fa40: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d const char *zSym
fa50: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 bol))(void);. v
fa60: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 oid (*xDlClose)(
fa70: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f sqlite3_vfs*, vo
fa80: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 id*);. int (*xR
fa90: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 andomness)(sqlit
faa0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 e3_vfs*, int nBy
fab0: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b te, char *zOut);
fac0: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 . int (*xSleep)
fad0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
fae0: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 nt microseconds)
faf0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 ;. int (*xCurre
fb00: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f ntTime)(sqlite3_
fb10: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a vfs*, double*);.
fb20: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 int (*xGetLast
fb30: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 Error)(sqlite3_v
fb40: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a fs*, int, char *
fb50: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 );. /*. ** The
fb60: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 methods above a
fb70: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 re in version 1
fb80: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 of the sqlite_vf
fb90: 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 s object. ** de
fba0: 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 finition. Those
fbb0: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 that follow are
fbc0: 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f added in versio
fbd0: 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a n 2 or later. *
fbe0: 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 /. int (*xCurre
fbf0: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c ntTimeInt64)(sql
fc00: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 ite3_vfs*, sqlit
fc10: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a e3_int64*);. /*
fc20: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 . ** The method
fc30: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 s above are in v
fc40: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 ersions 1 and 2
fc50: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 of the sqlite_vf
fc60: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 s object.. ** T
fc70: 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 hose below are f
fc80: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 or version 3 and
fc90: 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 greater.. */.
fca0: 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 int (*xSetSyste
fcb0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 mCall)(sqlite3_v
fcc0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
fcd0: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f *zName, sqlite3_
fce0: 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 syscall_ptr);.
fcf0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f sqlite3_syscall_
fd00: 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d ptr (*xGetSystem
fd10: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 Call)(sqlite3_vf
fd20: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
fd30: 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 zName);. const
fd40: 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 char *(*xNextSys
fd50: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 temCall)(sqlite3
fd60: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
fd70: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a r *zName);. /*.
fd80: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 ** The methods
fd90: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 above are in ve
fda0: 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 rsions 1 through
fdb0: 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 3 of the sqlite
fdc0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a _vfs object.. *
fdd0: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 * New fields may
fde0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 be appended in
fdf0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 2e future versions.
fe00: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 The iVersion.
fe10: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 ** value will i
fe20: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 ncrement wheneve
fe30: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 r this happens.
fe40: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 . */.};../*.**
fe50: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 CAPI3REF: Flags
fe60: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 for the xAccess
fe70: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a VFS method.**.**
fe80: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
fe90: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 onstants can be
fea0: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 used as the thir
feb0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a d parameter to.*
fec0: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 * the xAccess me
fed0: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 thod of an [sqli
fee0: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
fef0: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 They determine
ff00: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 .** what kind of
ff10: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 permissions the
ff20: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 xAccess method
ff30: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a is looking for..
ff40: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
ff50: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 CCESS_EXISTS, th
ff60: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
ff70: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b .** simply check
ff80: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 s whether the fi
ff90: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 le exists..** Wi
ffa0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
ffb0: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 _READWRITE, the
ffc0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a xAccess method.*
ffd0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 * checks whether
ffe0: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 the named direc
fff0: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 tory is both rea
10000 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 dable and writab
10010 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 le.** (in other
10020 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 words, if files
10030 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 can be added, re
10040 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d moved, and renam
10050 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 ed within.** the
10060 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 directory)..**
10070 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 The SQLITE_ACCES
10080 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 S_READWRITE cons
10090 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c tant is currentl
100a0 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 y used only by t
100b0 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 he.** [temp_stor
100c0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 e_directory prag
100d0 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 ma], though this
100e0 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e could change in
100f0 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c a future.** rel
10100 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a ease of SQLite..
10110 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
10120 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 CCESS_READ, the
10130 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a xAccess method.*
10140 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 * checks whether
10150 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 the file is rea
10160 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 dable. The SQLI
10170 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 TE_ACCESS_READ c
10180 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 onstant is.** cu
10190 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 rrently unused,
101a0 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 though it might
101b0 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 be used in a fut
101c0 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a ure release of.*
101d0 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 * SQLite..*/.#de
101e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 fine SQLITE_ACCE
101f0 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 SS_EXISTS 0.#
10200 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
10210 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 CESS_READWRITE 1
10220 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 /* Used by PR
10230 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f AGMA temp_store_
10240 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 directory */.#de
10250 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 fine SQLITE_ACCE
10260 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 SS_READ 2
10270 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f /* Unused */../
10280 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
10290 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 lags for the xSh
102a0 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 mLock VFS method
102b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 .**.** These int
102c0 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 eger constants d
102d0 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 efine the variou
102e0 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 s locking operat
102f0 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 ions.** allowed
10300 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 by the xShmLock
10310 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 method of [sqlit
10320 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 e3_io_methods].
10330 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e The.** followin
10340 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c g are the only l
10350 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e egal combination
10360 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 s of flags to th
10370 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 e.** xShmLock me
10380 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e thod:.**.** <ul>
10390 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
103a0 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 _SHM_LOCK | SQLI
103b0 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a TE_SHM_SHARED.**
103c0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 <li> SQLITE_SH
103d0 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f M_LOCK | SQLITE_
103e0 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a SHM_EXCLUSIVE.**
103f0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 <li> SQLITE_SH
10400 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 M_UNLOCK | SQLIT
10410 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 E_SHM_SHARED.**
10420 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d <li> SQLITE_SHM
10430 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 _UNLOCK | SQLITE
10440 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a _SHM_EXCLUSIVE.*
10450 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 * </ul>.**.** Wh
10460 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 en unlocking, th
10470 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 e same SHARED or
10480 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 EXCLUSIVE flag
10490 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 must be supplied
104a0 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e as.** was given
104b0 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f on the correspo
104c0 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a nding lock. .**
104d0 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b .** The xShmLock
104e0 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e method can tran
104f0 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 sition between u
10500 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 nlocked and SHAR
10510 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e ED or.** between
10520 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 unlocked and EX
10530 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e CLUSIVE. It can
10540 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 not transition b
10550 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a etween SHARED.**
10560 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a and EXCLUSIVE..
10570 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
10580 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 E_SHM_UNLOCK
10590 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
105a0 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 ITE_SHM_LOCK
105b0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
105c0 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 QLITE_SHM_SHARED
105d0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 4.#define
105e0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c SQLITE_SHM_EXCL
105f0 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a USIVE 8../*.*
10600 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 * CAPI3REF: Maxi
10610 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 mum xShmLock ind
10620 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 ex.**.** The xSh
10630 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 mLock method on
10640 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
10650 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c ods] may use val
10660 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 ues.** between 0
10670 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 and this upper
10680 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 bound as its "of
10690 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a fset" argument..
106a0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f ** The SQLite co
106b0 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 re will never at
106c0 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 tempt to acquire
106d0 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a or release a.**
106e0 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 lock outside of
106f0 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 this range.*/.#
10700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
10710 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 M_NLOCK 8
10720 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
10730 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 F: Initialize Th
10740 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 e SQLite Library
10750 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
10760 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
10770 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c routine initial
10780 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 izes the.** SQLi
10790 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 te library. ^Th
107a0 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f e sqlite3_shutdo
107b0 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 wn() routine.**
107c0 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 deallocates any
107d0 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 resources that w
107e0 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 ere allocated by
107f0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
10800 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 ize()..** These
10810 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 routines are des
10820 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 igned to aid in
10830 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 process initiali
10840 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 zation and.** sh
10850 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 utdown on embedd
10860 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 ed systems. Wor
10870 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 kstation applica
10880 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 tions using.** S
10890 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 QLite normally d
108a0 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e o not need to in
108b0 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 voke either of t
108c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a hese routines..*
108d0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 *.** A call to s
108e0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
108f0 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 e() is an "effec
10900 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 tive" call if it
10910 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 is.** the first
10920 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e time sqlite3_in
10930 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e itialize() is in
10940 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 voked during the
10950 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 lifetime of.**
10960 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 the process, or
10970 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 if it is the fir
10980 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f st time sqlite3_
10990 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
109a0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f invoked.** follo
109b0 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 wing a call to s
109c0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
109d0 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 ). ^(Only an ef
109e0 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 fective call.**
109f0 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 of sqlite3_initi
10a00 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 alize() does any
10a10 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e initialization.
10a20 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c All other call
10a30 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 s.** are harmles
10a40 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a s no-ops.)^.**.*
10a50 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 * A call to sqli
10a60 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 te3_shutdown() i
10a70 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 s an "effective"
10a80 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 call if it is t
10a90 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c he first.** call
10aa0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 to sqlite3_shut
10ab0 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 down() since the
10ac0 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e last sqlite3_in
10ad0 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f itialize(). ^(O
10ae0 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 nly.** an effect
10af0 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ive call to sqli
10b00 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 te3_shutdown() d
10b10 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 oes any deinitia
10b20 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c lization..** All
10b30 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c other valid cal
10b40 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ls to sqlite3_sh
10b50 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 utdown() are har
10b60 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a mless no-ops.)^.
10b70 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
10b80 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
10b90 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65 nterface is thre
10ba0 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 adsafe, but sqli
10bb0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a te3_shutdown().*
10bc0 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 * is not. The s
10bd0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
10be0 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 ) interface must
10bf0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 only be called
10c00 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 from a.** single
10c10 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 thread. All op
10c20 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e en [database con
10c30 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 nections] must b
10c40 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c e closed and all
10c50 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 .** other SQLite
10c60 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 resources must
10c70 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 be deallocated p
10c80 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 rior to invoking
10c90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 .** sqlite3_shut
10ca0 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d down()..**.** Am
10cb0 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 ong other things
10cc0 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 , ^sqlite3_initi
10cd0 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 alize() will inv
10ce0 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f oke.** sqlite3_o
10cf0 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c s_init(). Simil
10d00 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 arly, ^sqlite3_s
10d10 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c hutdown().** wil
10d20 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 l invoke sqlite3
10d30 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a _os_end()..**.**
10d40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
10d50 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
10d60 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ne returns [SQLI
10d70 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
10d80 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f s..** ^If for so
10d90 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 me reason, sqlit
10da0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
10db0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 is unable to ini
10dc0 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c tialize.** the l
10dd0 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 ibrary (perhaps
10de0 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 it is unable to
10df0 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 allocate a neede
10e00 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a d resource such.
10e10 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 ** as a mutex) i
10e20 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 t returns an [er
10e30 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 ror code] other
10e40 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d than [SQLITE_OK]
10e50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
10e60 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
10e70 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c ) routine is cal
10e80 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 led internally b
10e90 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 y many other.**
10ea0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
10eb0 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 s so that an app
10ec0 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 lication usually
10ed0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
10ee0 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 o.** invoke sqli
10ef0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
10f00 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 directly. For
10f10 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 example, [sqlite
10f20 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 3_open()].** cal
10f30 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ls sqlite3_initi
10f40 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 alize() so the S
10f50 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 QLite library wi
10f60 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 ll be automatica
10f70 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a lly.** initializ
10f80 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 ed when [sqlite3
10f90 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c _open()] is call
10fa0 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 ed if it has not
10fb0 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a be initialized.
10fc0 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f ** already. ^Ho
10fd0 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 wever, if SQLite
10fe0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
10ff0 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d h the [SQLITE_OM
11000 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 IT_AUTOINIT].**
11010 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
11020 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 ion, then the au
11030 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f tomatic calls to
11040 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
11050 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 ize().** are omi
11060 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 tted and the app
11070 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 lication must ca
11080 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ll sqlite3_initi
11090 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 alize() directly
110a0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 .** prior to usi
110b0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c ng any other SQL
110c0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ite interface.
110d0 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 For maximum port
110e0 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 ability,.** it i
110f0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 s recommended th
11100 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 at applications
11110 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 always invoke sq
11120 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
11130 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 ().** directly p
11140 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e rior to using an
11150 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 y other SQLite i
11160 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 nterface. Futur
11170 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 e releases.** of
11180 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 SQLite may requ
11190 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 ire this. In ot
111a0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 her words, the b
111b0 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 ehavior exhibite
111c0 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 d.** when SQLite
111d0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
111e0 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 h [SQLITE_OMIT_A
111f0 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 UTOINIT] might b
11200 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 ecome the.** def
11210 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e ault behavior in
11220 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c some future rel
11230 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a ease of SQLite..
11240 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
11250 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 3_os_init() rout
11260 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 ine does operati
11270 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 ng-system specif
11280 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 ic.** initializa
11290 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 tion of the SQLi
112a0 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 te library. The
112b0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
112c0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 ).** routine und
112d0 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f oes the effect o
112e0 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 f sqlite3_os_ini
112f0 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 t(). Typical ta
11300 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 sks.** performed
11310 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e by these routin
11320 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 es include alloc
11330 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 ation or dealloc
11340 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 ation.** of stat
11350 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e ic resources, in
11360 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 itialization of
11370 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 global variables
11380 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 ,.** setting up
11390 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 a default [sqlit
113a0 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 e3_vfs] module,
113b0 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a or setting up.**
113c0 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 a default confi
113d0 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b guration using [
113e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
113f0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 ]..**.** The app
11400 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
11410 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 never invoke eit
11420 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 her sqlite3_os_i
11430 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 nit().** or sqli
11440 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 te3_os_end() dir
11450 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c ectly. The appl
11460 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f ication should o
11470 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 nly invoke.** sq
11480 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
11490 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 () and sqlite3_s
114a0 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 hutdown(). The
114b0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
114c0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 ).** interface i
114d0 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 s called automat
114e0 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 ically by sqlite
114f0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 3_initialize() a
11500 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 nd.** sqlite3_os
11510 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 _end() is called
11520 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 by sqlite3_shut
11530 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 down(). Appropr
11540 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e iate.** implemen
11550 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 tations for sqli
11560 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e te3_os_init() an
11570 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 d sqlite3_os_end
11580 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 ().** are built
11590 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e into SQLite when
115a0 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 it is compiled
115b0 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 for Unix, Window
115c0 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 s, or OS/2..** W
115d0 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c hen [custom buil
115e0 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f ds | built for o
115f0 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a ther platforms].
11600 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 ** (using the [S
11610 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 QLITE_OS_OTHER=1
11620 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a ] compile-time.*
11630 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 * option) the ap
11640 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 plication must s
11650 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 upply a suitable
11660 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
11670 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f for.** sqlite3_o
11680 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c s_init() and sql
11690 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 ite3_os_end().
116a0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 An application-s
116b0 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 upplied.** imple
116c0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c mentation of sql
116d0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f ite3_os_init() o
116e0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 r sqlite3_os_end
116f0 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 ().** must retur
11700 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e n [SQLITE_OK] on
11710 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d success and som
11720 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 e other [error c
11730 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 ode] upon.** fai
11740 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c lure..*/.int sql
11750 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
11760 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 void);.int sqlit
11770 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 e3_shutdown(void
11780 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f );.int sqlite3_o
11790 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e s_init(void);.in
117a0 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 t sqlite3_os_end
117b0 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 (void);../*.** C
117c0 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
117d0 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 ring The SQLite
117e0 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 Library.**.** Th
117f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
11800 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
11810 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f used to make glo
11820 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f bal configuratio
11830 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 n.** changes to
11840 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 SQLite in order
11850 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 to tune SQLite t
11860 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e o the specific n
11870 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 eeds of.** the a
11880 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 pplication. The
11890 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
118a0 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d ration is recomm
118b0 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a ended for most.*
118c0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 * applications a
118d0 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 nd so this routi
118e0 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f ne is usually no
118f0 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 t necessary. It
11900 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 is.** provided
11910 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 to support rare
11920 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 applications wit
11930 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e h unusual needs.
11940 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 .**.** <b>The sq
11950 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
11960 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
11970 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65 20 threadsafe. The
11980 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d application.** m
11990 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 ust ensure that
119a0 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 no other SQLite
119b0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 interfaces are i
119c0 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a nvoked by other.
119d0 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 ** threads while
119e0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
119f0 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 ) is running.</b
11a00 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
11a10 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 te3_config() int
11a20 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e erface.** may on
11a30 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 ly be invoked pr
11a40 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 ior to library i
11a50 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 nitialization us
11a60 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
11a70 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 initialize()] or
11a80 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 after shutdown
11a90 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 by [sqlite3_shut
11aa0 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 down()]..** ^If
11ab0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
11ac0 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 is called after
11ad0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
11ae0 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f lize()] and befo
11af0 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 re.** [sqlite3_s
11b00 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 hutdown()] then
11b10 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 it will return S
11b20 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a QLITE_MISUSE..**
11b30 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 Note, however,
11b40 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f that ^sqlite3_co
11b50 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 nfig() can be ca
11b60 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 lled as part of
11b70 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
11b80 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c ation of an appl
11b90 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
11ba0 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 [sqlite3_os_init
11bb0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ()]..**.** The f
11bc0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
11bd0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
11be0 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a ) is an integer.
11bf0 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f ** [configuratio
11c00 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 n option] that d
11c10 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 etermines.** wha
11c20 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 t property of SQ
11c30 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f Lite is to be co
11c40 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 nfigured. Subse
11c50 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a quent arguments.
11c60 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e ** vary dependin
11c70 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 g on the [config
11c80 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a uration option].
11c90 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ** in the first
11ca0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
11cb0 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 ^When a configur
11cc0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 ation option is
11cd0 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e set, sqlite3_con
11ce0 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 fig() returns [S
11cf0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 QLITE_OK]..** ^I
11d00 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 f the option is
11d10 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 unknown or SQLit
11d20 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 e is unable to s
11d30 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a et the option.**
11d40 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 then this routi
11d50 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e ne returns a non
11d60 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 -zero [error cod
11d70 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 e]..*/.int sqlit
11d80 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e e3_config(int, .
11d90 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
11da0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 3REF: Configure
11db0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
11dc0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ions.** METHOD:
11dd0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 sqlite3.**.** Th
11de0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e e sqlite3_db_con
11df0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
11e00 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 is used to make
11e10 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a configuration.**
11e20 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 changes to a [d
11e30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
11e40 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 on]. The interf
11e50 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 ace is similar t
11e60 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
11e70 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 nfig()] except t
11e80 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 hat the changes
11e90 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c apply to a singl
11ea0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
11eb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 onnection] (spec
11ec0 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 ified in the fir
11ed0 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a st argument)..**
11ee0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 .** The second a
11ef0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
11f00 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 e3_db_config(D,V
11f10 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a ,...) is the.**
11f20 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 [SQLITE_DBCONFI
11f30 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f G_LOOKASIDE | co
11f40 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 nfiguration verb
11f50 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 ] - an integer c
11f60 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 ode .** that ind
11f70 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65 icates what aspe
11f80 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 ct of the [datab
11f90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
11fa0 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 is being configu
11fb0 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 red..** Subseque
11fc0 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 nt arguments var
11fd0 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 y depending on t
11fe0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e he configuration
11ff0 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 verb..**.** ^Ca
12000 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 lls to sqlite3_d
12010 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 b_config() retur
12020 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 n SQLITE_OK if a
12030 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 nd only if.** th
12040 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 e call is consid
12050 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e ered successful.
12060 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
12070 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 db_config(sqlite
12080 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3*, int op, ...)
12090 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
120a0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 F: Memory Alloca
120b0 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a tion Routines.**
120c0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
120d0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 of this object d
120e0 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 efines the inter
120f0 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c face between SQL
12100 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c ite.** and low-l
12110 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f evel memory allo
12120 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e cation routines.
12130 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 .**.** This obje
12140 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e ct is used in on
12150 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 ly one place in
12160 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 the SQLite inter
12170 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 face..** A point
12180 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
12190 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
121a0 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 is the argument
121b0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
121c0 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 config()] when t
121d0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e he configuration
121e0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 option is.** [S
121f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
12200 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f LOC] or [SQLITE_
12210 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
12220 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 ]. .** By creat
12230 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 ing an instance
12240 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a of this object.*
12250 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 * and passing it
12260 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e to [sqlite3_con
12270 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e fig]([SQLITE_CON
12280 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 FIG_MALLOC]).**
12290 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 during configura
122a0 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 tion, an applica
122b0 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 tion can specify
122c0 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a an alternative.
122d0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
122e0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 tion subsystem f
122f0 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 or SQLite to use
12300 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a for all of its.
12310 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 ** dynamic memor
12320 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e y needs..**.** N
12330 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 ote that SQLite
12340 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 comes with sever
12350 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d al [built-in mem
12360 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a ory allocators].
12370 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66 ** that are perf
12380 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 ectly adequate f
12390 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d or the overwhelm
123a0 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 ing majority of
123b0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
123c0 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 and that this ob
123d0 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 ject is only use
123e0 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 ful to a tiny mi
123f0 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 nority of applic
12400 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 ations.** with s
12410 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 pecialized memor
12420 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 y allocation req
12430 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 uirements. This
12440 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c object is.** al
12450 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 so used during t
12460 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 esting of SQLite
12470 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 in order to spe
12480 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 cify an alternat
12490 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c ive.** memory al
124a0 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d locator that sim
124b0 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 ulates memory ou
124c0 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 t-of-memory cond
124d0 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 itions in.** ord
124e0 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 er to verify tha
124f0 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 t SQLite recover
12500 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f s gracefully fro
12510 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 m such.** condit
12520 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ions..**.** The
12530 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f xMalloc, xReallo
12540 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 c, and xFree met
12550 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c hods must work l
12560 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f ike the.** mallo
12570 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 c(), realloc() a
12580 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 nd free() functi
12590 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 ons from the sta
125a0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e ndard C library.
125b0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 .** ^SQLite guar
125c0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 antees that the
125d0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
125e0 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 to.** xRealloc i
125f0 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 s always a value
12600 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 returned by a p
12610 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f rior call to xRo
12620 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 undup..**.** xSi
12630 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e ze should return
12640 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 the allocated s
12650 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 ize of a memory
12660 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 allocation.** pr
12670 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 eviously obtaine
12680 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f d from xMalloc o
12690 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 r xRealloc. The
126a0 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a allocated size.
126b0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 ** is always at
126c0 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 least as big as
126d0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 the requested si
126e0 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 ze but may be la
126f0 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rger..**.** The
12700 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 xRoundup method
12710 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 returns what wou
12720 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 ld be the alloca
12730 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 ted size of.** a
12740 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
12750 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 on given a parti
12760 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 cular requested
12770 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f size. Most memo
12780 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 ry.** allocators
12790 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 round up memory
127a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 allocations at
127b0 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 least to the nex
127c0 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 t multiple.** of
127d0 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 8. Some alloca
127e0 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f tors round up to
127f0 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 a larger multip
12800 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 le or to a power
12810 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 of 2..** Every
12820 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
12830 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 n request coming
12840 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c in through [sql
12850 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a ite3_malloc()].*
12860 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 * or [sqlite3_re
12870 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 alloc()] first c
12880 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 alls xRoundup.
12890 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 If xRoundup retu
128a0 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 rns 0, .** that
128b0 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 causes the corre
128c0 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 sponding memory
128d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 allocation to fa
128e0 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 il..**.** The xI
128f0 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 nit method initi
12900 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 alizes the memor
12910 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f y allocator. Fo
12920 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 r example,.** it
12930 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 might allocate
12940 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 any require mute
12950 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a xes or initializ
12960 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a e internal data.
12970 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 ** structures.
12980 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 The xShutdown me
12990 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 thod is invoked
129a0 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a (indirectly) by.
129b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 ** [sqlite3_shut
129c0 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 down()] and shou
129d0 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e ld deallocate an
129e0 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 y resources acqu
129f0 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 ired.** by xInit
12a00 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 . The pAppData
12a10 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 pointer is used
12a20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 as the only para
12a30 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 meter to.** xIni
12a40 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e t and xShutdown.
12a50 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f .**.** SQLite ho
12a60 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f lds the [SQLITE_
12a70 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 MUTEX_STATIC_MAS
12a80 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 TER] mutex when
12a90 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 it invokes.** th
12aa0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 e xInit method,
12ab0 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 so the xInit met
12ac0 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 hod need not be
12ad0 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 threadsafe. The
12ae0 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 .** xShutdown me
12af0 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c thod is only cal
12b00 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 led from [sqlite
12b10 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 3_shutdown()] so
12b20 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 it does.** not
12b30 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 need to be threa
12b40 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 dsafe either. F
12b50 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 or all other met
12b60 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 hods, SQLite.**
12b70 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 holds the [SQLIT
12b80 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d E_MUTEX_STATIC_M
12b90 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e EM] mutex as lon
12ba0 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c g as the.** [SQL
12bb0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
12bc0 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 ATUS] configurat
12bd0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 ion option is tu
12be0 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a rned on (which.*
12bf0 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 * it is by defau
12c00 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d lt) and so the m
12c10 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d ethods are autom
12c20 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 atically seriali
12c30 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c zed..** However,
12c40 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 if [SQLITE_CONF
12c50 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 IG_MEMSTATUS] is
12c60 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 disabled, then
12c70 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 the other.** met
12c80 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 hods must be thr
12c90 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 eadsafe or else
12ca0 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 make their own a
12cb0 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a rrangements for.
12cc0 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e ** serialization
12cd0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 ..**.** SQLite w
12ce0 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 ill never invoke
12cf0 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 xInit() more th
12d00 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 an once without
12d10 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a an intervening.*
12d20 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 * call to xShutd
12d30 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 own()..*/.typede
12d40 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
12d50 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c _mem_methods sql
12d60 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
12d70 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
12d80 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 _mem_methods {.
12d90 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 void *(*xMalloc
12da0 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 )(int);
12db0 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 /* Memory alloca
12dc0 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f tion function */
12dd0 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 . void (*xFree)
12de0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
12df0 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f /* Free a prio
12e00 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a r allocation */.
12e10 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c void *(*xReall
12e20 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 oc)(void*,int);
12e30 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c /* Resize an al
12e40 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e location */. in
12e50 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a t (*xSize)(void*
12e60 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ); /*
12e70 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 Return the size
12e80 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e of an allocation
12e90 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 */. int (*xRou
12ea0 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 ndup)(int);
12eb0 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 /* Round up
12ec0 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f request size to
12ed0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 allocation size
12ee0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 */. int (*xIni
12ef0 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 t)(void*);
12f00 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 /* Initiali
12f10 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c ze the memory al
12f20 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 locator */. voi
12f30 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 d (*xShutdown)(v
12f40 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 oid*); /* D
12f50 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 einitialize the
12f60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
12f70 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 */. void *pApp
12f80 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 Data;
12f90 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 /* Argument
12fa0 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 to xInit() and
12fb0 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d xShutdown() */.}
12fc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
12fd0 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e F: Configuration
12fe0 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 Options.** KEYW
12ff0 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 ORDS: {configura
13000 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a tion option}.**.
13010 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
13020 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c ts are the avail
13030 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e able integer con
13040 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
13050 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 ns that.** can b
13060 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
13070 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
13080 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 o the [sqlite3_c
13090 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 onfig()] interfa
130a0 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f ce..**.** New co
130b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
130c0 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 ons may be added
130d0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
130e0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ses of SQLite..*
130f0 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 * Existing confi
13100 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
13110 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e might be discon
13120 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 tinued. Applica
13130 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 tions.** should
13140 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e check the return
13150 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 code from [sqli
13160 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f te3_config()] to
13170 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a make sure that.
13180 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b ** the call work
13190 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 ed. The [sqlite
131a0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 3_config()] inte
131b0 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 rface will retur
131c0 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 n a.** non-zero
131d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 [error code] if
131e0 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f a discontinued o
131f0 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f r unsupported co
13200 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
13210 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 on.** is invoked
13220 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ..**.** <dl>.**
13230 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
13240 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c SINGLETHREAD]] <
13250 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
13260 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 _SINGLETHREAD</d
13270 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 t>.** <dd>There
13280 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 are no arguments
13290 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e to this option.
132a0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 ^This option s
132b0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 ets the.** [thre
132c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 ading mode] to S
132d0 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 ingle-thread. I
132e0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 n other words, i
132f0 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c t disables.** al
13300 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 l mutexing and p
13310 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 uts SQLite into
13320 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 a mode where it
13330 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 can only be used
13340 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 .** by a single
13350 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 thread. ^If SQ
13360 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
13370 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 with.** the [SQ
13380 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 LITE_THREADSAFE
13390 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 | SQLITE_THREADS
133a0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 AFE=0] compile-t
133b0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a ime option then.
133c0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 ** it is not pos
133d0 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 sible to change
133e0 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d the [threading m
133f0 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 ode] from its de
13400 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f fault.** value o
13410 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 f Single-thread
13420 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f and so [sqlite3_
13430 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 config()] will r
13440 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 eturn .** [SQLIT
13450 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c E_ERROR] if call
13460 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 ed with the SQLI
13470 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
13480 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 THREAD.** config
13490 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c uration option.<
134a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
134b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
134c0 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c THREAD]] <dt>SQL
134d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
134e0 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c THREAD</dt>.** <
134f0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 dd>There are no
13500 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 arguments to thi
13510 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 s option. ^This
13520 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 option sets the
13530 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d .** [threading m
13540 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 ode] to Multi-th
13550 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 read. In other
13560 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c words, it disabl
13570 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f es.** mutexing o
13580 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
13590 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 ection] and [pre
135a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
135b0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 objects..** The
135c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 application is
135d0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 responsible for
135e0 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 serializing acce
135f0 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 ss to.** [databa
13600 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 se connections]
13610 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
13620 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 atements]. But
13630 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a other mutexes.**
13640 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 are enabled so
13650 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c that SQLite will
13660 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 be safe to use
13670 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 in a multi-threa
13680 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 ded.** environme
13690 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f nt as long as no
136a0 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 two threads att
136b0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 empt to use the
136c0 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 same.** [databas
136d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 e connection] at
136e0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 the same time.
136f0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
13700 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
13710 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
13720 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
13730 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
13740 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
13750 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 n then.** it is
13760 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 not possible to
13770 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 set the Multi-th
13780 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 read [threading
13790 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 mode] and.** [sq
137a0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
137b0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c will return [SQL
137c0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 ITE_ERROR] if ca
137d0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a lled with the.**
137e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
137f0 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 ULTITHREAD confi
13800 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e guration option.
13810 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
13820 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
13830 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c ALIZED]] <dt>SQL
13840 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
13850 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 LIZED</dt>.** <d
13860 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 d>There are no a
13870 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
13880 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 option. ^This
13890 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a option sets the.
138a0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ** [threading mo
138b0 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 de] to Serialize
138c0 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 d. In other word
138d0 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 s, this option e
138e0 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 nables.** all mu
138f0 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 texes including
13900 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a the recursive.**
13910 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 mutexes on [dat
13920 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
13930 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 ] and [prepared
13940 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 statement] objec
13950 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d ts..** In this m
13960 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 ode (which is th
13970 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 e default when S
13980 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
13990 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 d with.** [SQLIT
139a0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 E_THREADSAFE=1])
139b0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
139c0 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 ary will itself
139d0 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 serialize access
139e0 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 .** to [database
139f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e connections] an
13a00 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
13a10 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 ements] so that
13a20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 the.** applicati
13a30 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 on is free to us
13a40 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 e the same [data
13a50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
13a60 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 or the.** same
13a70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
13a80 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e ent] in differen
13a90 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 t threads at the
13aa0 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e same time..** ^
13ab0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
13ac0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
13ad0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
13ae0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
13af0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
13b00 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
13b10 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f then.** it is no
13b20 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 t possible to se
13b30 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 t the Serialized
13b40 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
13b50 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
13b60 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 3_config()] will
13b70 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
13b80 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 ERROR] if called
13b90 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c with the.** SQL
13ba0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
13bb0 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 LIZED configurat
13bc0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e ion option.</dd>
13bd0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
13be0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 CONFIG_MALLOC]]
13bf0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
13c00 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a G_MALLOC</dt>.**
13c10 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 <dd> ^(The SQLI
13c20 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
13c30 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
13c40 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
13c50 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 which is .** a p
13c60 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
13c70 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 tance of the [sq
13c80 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
13c90 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a s] structure..**
13ca0 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 The argument sp
13cb0 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 ecifies.** alter
13cc0 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c native low-level
13cd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
13ce0 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 on routines to b
13cf0 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 e used in place
13d00 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 of.** the memory
13d10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
13d20 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 ines built into
13d30 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 SQLite.)^ ^SQLit
13d40 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f e makes.** its o
13d50 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 wn private copy
13d60 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f of the content o
13d70 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
13d80 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
13d90 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 cture.** before
13da0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
13db0 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 fig()] call retu
13dc0 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 rns.</dd>.**.**
13dd0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
13de0 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e GETMALLOC]] <dt>
13df0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
13e00 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 TMALLOC</dt>.**
13e10 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 <dd> ^(The SQLIT
13e20 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
13e30 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 OC option takes
13e40 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
13e50 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 t which.** is a
13e60 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
13e70 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
13e80 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
13e90 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a ds] structure..*
13ea0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d * The [sqlite3_m
13eb0 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 em_methods].** s
13ec0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c tructure is fill
13ed0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 ed with the curr
13ee0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 ently defined me
13ef0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
13f00 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 routines.)^.** T
13f10 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 his option can b
13f20 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f e used to overlo
13f30 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d ad the default m
13f40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
13f50 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 .** routines wit
13f60 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 h a wrapper that
13f70 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d simulations mem
13f80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
13f90 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 ailure or.** tra
13fa0 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 cks memory usage
13fb0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c , for example. <
13fc0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
13fd0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c ITE_CONFIG_SMALL
13fe0 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 _MALLOC]] <dt>SQ
13ff0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c LITE_CONFIG_SMAL
14000 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a L_MALLOC</dt>.**
14010 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 <dd> ^The SQLIT
14020 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d E_CONFIG_SMALL_M
14030 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b ALLOC option tak
14040 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 es single argume
14050 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65 20 69 6e nt of.** type in
14060 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 t, interpreted a
14070 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 s a boolean, whi
14080 63 68 20 69 66 20 74 72 75 65 20 70 72 6f 76 69 ch if true provi
14090 64 65 73 20 61 20 68 69 6e 74 20 74 6f 0a 2a 2a des a hint to.**
140a0 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 SQLite that it
140b0 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 6c 61 72 should avoid lar
140c0 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ge memory alloca
140d0 74 69 6f 6e 73 20 69 66 20 70 6f 73 73 69 62 6c tions if possibl
140e0 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c e..** SQLite wil
140f0 6c 20 72 75 6e 20 66 61 73 74 65 72 20 69 66 20 l run faster if
14100 69 74 20 69 73 20 66 72 65 65 20 74 6f 20 6d 61 it is free to ma
14110 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 ke large memory
14120 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a 2a 20 allocations,.**
14130 62 75 74 20 73 6f 6d 65 20 61 70 70 6c 69 63 61 but some applica
14140 74 69 6f 6e 20 6d 69 67 68 74 20 70 72 65 66 65 tion might prefe
14150 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77 65 72 20 r to run slower
14160 69 6e 20 65 78 63 68 61 6e 67 65 20 66 6f 72 0a in exchange for.
14170 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 61 62 ** guarantees ab
14180 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72 61 67 6d out memory fragm
14190 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 61 72 entation that ar
141a0 65 20 70 6f 73 73 69 62 6c 65 20 69 66 20 6c 61 e possible if la
141b0 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f rge.** allocatio
141c0 6e 73 20 61 72 65 20 61 76 6f 69 64 65 64 2e 20 ns are avoided.
141d0 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f This hint is no
141e0 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a 20 3c rmally off..** <
141f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
14200 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
14210 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 ATUS]] <dt>SQLIT
14220 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
14230 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 US</dt>.** <dd>
14240 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
14250 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 IG_MEMSTATUS opt
14260 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 ion takes single
14270 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 argument of typ
14280 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 e int,.** interp
14290 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 reted as a boole
142a0 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 an, which enable
142b0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 s or disables th
142c0 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a e collection of.
142d0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
142e0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e tion statistics.
142f0 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 ^(When memory a
14300 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 llocation statis
14310 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 tics are.** disa
14320 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 bled, the follow
14330 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 ing SQLite inter
14340 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e faces become non
14350 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a -operational:.**
14360 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 <ul>.** <li
14370 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 > [sqlite3_memor
14380 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c y_used()].** <
14390 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d li> [sqlite3_mem
143a0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d ory_highwater()]
143b0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 .** <li> [sqli
143c0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 te3_soft_heap_li
143d0 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c mit64()].** <l
143e0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 i> [sqlite3_stat
143f0 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 us64()].** </u
14400 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 l>)^.** ^Memory
14410 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 allocation stati
14420 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 stics are enable
14430 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c d by default unl
14440 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a ess SQLite is.**
14450 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b compiled with [
14460 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d SQLITE_DEFAULT_M
14470 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 EMSTATUS]=0 in w
14480 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 hich case memory
14490 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 .** allocation s
144a0 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 tatistics are di
144b0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
144c0 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a t..** </dd>.**.*
144d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
144e0 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e G_SCRATCH]] <dt>
144f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
14500 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 RATCH</dt>.** <d
14510 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f d> The SQLITE_CO
14520 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 NFIG_SCRATCH opt
14530 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 ion is no longer
14540 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a used..** </dd>.
14550 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
14560 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d ONFIG_PAGECACHE]
14570 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
14580 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 FIG_PAGECACHE</d
14590 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 t>.** <dd> ^The
145a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
145b0 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 GECACHE option s
145c0 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 pecifies a memor
145d0 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 y pool.** that S
145e0 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f QLite can use fo
145f0 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 r the database p
14600 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 age cache with t
14610 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a he default page.
14620 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 ** cache impleme
14630 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 ntation. .** Th
14640 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e is configuration
14650 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d option is a no-
14660 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 op if an applica
14670 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 tion-define page
14680 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d .** cache implem
14690 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 entation is load
146a0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 ed using the [SQ
146b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
146c0 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 HE2]..** ^There
146d0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
146e0 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f nts to SQLITE_CO
146f0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 NFIG_PAGECACHE:
14700 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 A pointer to.**
14710 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 8-byte aligned m
14720 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 emory (pMem), th
14730 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 e size of each p
14740 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 age cache line (
14750 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 sz),.** and the
14760 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 number of cache
14770 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 lines (N)..** Th
14780 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 e sz argument sh
14790 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 ould be the size
147a0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 of the largest
147b0 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a database page.**
147c0 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f (a power of two
147d0 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 between 512 and
147e0 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65536) plus som
147f0 65 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f e extra bytes fo
14800 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 r each.** page h
14810 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d eader. ^The num
14820 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 ber of extra byt
14830 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 es needed by the
14840 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 page header.**
14850 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 can be determine
14860 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f d using [SQLITE_
14870 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 CONFIG_PCACHE_HD
14880 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 RSZ]..** ^It is
14890 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 harmless, apart
148a0 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 from the wasted
148b0 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 memory,.** for t
148c0 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 he sz parameter
148d0 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 to be larger tha
148e0 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 n necessary. Th
148f0 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 e pMem.** argume
14900 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 nt must be eithe
14910 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 r a NULL pointer
14920 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f or a pointer to
14930 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c an 8-byte.** al
14940 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d igned block of m
14950 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 emory of at leas
14960 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 t sz*N bytes, ot
14970 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 herwise.** subse
14980 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 quent behavior i
14990 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 s undefined..**
149a0 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f ^When pMem is no
149b0 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 t NULL, SQLite w
149c0 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 ill strive to us
149d0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f e the memory pro
149e0 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 vided.** to sati
149f0 73 66 79 20 70 61 67 65 20 63 61 63 68 65 20 6e sfy page cache n
14a00 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 eeds, falling ba
14a10 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d ck to [sqlite3_m
14a20 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 alloc()] if.** a
14a30 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 page cache line
14a40 20 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 is larger than
14a50 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 sz bytes or if a
14a60 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 ll of the pMem b
14a70 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 uffer.** is exha
14a80 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d usted..** ^If pM
14a90 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e em is NULL and N
14aa0 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 is non-zero, th
14ab0 65 6e 20 65 61 63 68 20 64 61 74 61 62 61 73 65 en each database
14ac0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 connection.** d
14ad0 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 oes an initial b
14ae0 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ulk allocation f
14af0 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 or page cache me
14b00 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 mory.** from [sq
14b10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
14b20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e sufficient for N
14b30 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 cache lines if
14b40 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 N is positive or
14b50 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 .** of -1024*N b
14b60 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 ytes if N is neg
14b70 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 ative, . ^If add
14b80 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 itional.** page
14b90 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 cache memory is
14ba0 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 needed beyond wh
14bb0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 at is provided b
14bc0 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a y the initial.**
14bd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 allocation, the
14be0 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f n SQLite goes to
14bf0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
14c00 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 ()] separately f
14c10 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 or each.** addit
14c20 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 ional cache line
14c30 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b . </dd>.**.** [[
14c40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 SQLITE_CONFIG_HE
14c50 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f AP]] <dt>SQLITE_
14c60 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e CONFIG_HEAP</dt>
14c70 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 .** <dd> ^The SQ
14c80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
14c90 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 option specifie
14ca0 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 s a static memor
14cb0 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 y buffer .** tha
14cc0 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 t SQLite will us
14cd0 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 e for all of its
14ce0 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 dynamic memory
14cf0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
14d00 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 .** beyond those
14d10 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 provided for by
14d20 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
14d30 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e PAGECACHE]..** ^
14d40 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
14d50 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 G_HEAP option is
14d60 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 only available
14d70 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d if SQLite is com
14d80 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 piled.** with ei
14d90 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 ther [SQLITE_ENA
14da0 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 BLE_MEMSYS3] or
14db0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d [SQLITE_ENABLE_M
14dc0 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 EMSYS5] and retu
14dd0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 rns.** [SQLITE_E
14de0 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 RROR] if invoked
14df0 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e otherwise..** ^
14e00 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 There are three
14e10 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c arguments to SQL
14e20 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a ITE_CONFIG_HEAP:
14e30 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c .** An 8-byte al
14e40 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f igned pointer to
14e50 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 the memory,.**
14e60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
14e70 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 tes in the memor
14e80 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 y buffer, and th
14e90 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 e minimum alloca
14ea0 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 tion size..** ^I
14eb0 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e f the first poin
14ec0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 ter (the memory
14ed0 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c pointer) is NULL
14ee0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 , then SQLite re
14ef0 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e verts.** to usin
14f00 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 g its default me
14f10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 mory allocator (
14f20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f the system mallo
14f30 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 c() implementati
14f40 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 on),.** undoing
14f50 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 any prior invoca
14f60 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f tion of [SQLITE_
14f70 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 CONFIG_MALLOC].
14f80 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f ^If the.** memo
14f90 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f ry pointer is no
14fa0 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 t NULL then the
14fb0 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f alternative memo
14fc0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 ry.** allocator
14fd0 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 is engaged to ha
14fe0 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 ndle all of SQLi
14ff0 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 tes memory alloc
15000 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 ation needs..**
15010 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 The first pointe
15020 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f r (the memory po
15030 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 inter) must be a
15040 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 ligned to an 8-b
15050 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 yte.** boundary
15060 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 or subsequent be
15070 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 havior of SQLite
15080 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e will be undefin
15090 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d ed..** The minim
150a0 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 um allocation si
150b0 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20 ze is capped at
150c0 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 2**12. Reasonabl
150d0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 e values.** for
150e0 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f the minimum allo
150f0 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 cation size are
15100 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 2**5 through 2**
15110 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 8.</dd>.**.** [[
15120 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
15130 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 TEX]] <dt>SQLITE
15140 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 _CONFIG_MUTEX</d
15150 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 t>.** <dd> ^(The
15160 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
15170 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 UTEX option take
15180 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
15190 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a ent which is a.*
151a0 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 * pointer to an
151b0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
151c0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
151d0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
151e0 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 e..** The argume
151f0 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 nt specifies alt
15200 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 ernative low-lev
15210 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 el mutex routine
15220 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 s to be used.**
15230 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 in place the mut
15240 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c ex routines buil
15250 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e t into SQLite.)^
15260 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ^SQLite makes
15270 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 a copy of.** the
15280 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
15290 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
152a0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
152b0 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c e before the cal
152c0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
152d0 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 _config()] retur
152e0 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 ns. ^If SQLite i
152f0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
15300 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
15310 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
15320 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
15330 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
15340 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 tion then.** the
15350 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 entire mutexing
15360 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d subsystem is om
15370 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 itted from the b
15380 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 uild and hence c
15390 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 alls to.** [sqli
153a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
153b0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f th the SQLITE_CO
153c0 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 NFIG_MUTEX confi
153d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
153e0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b will.** return [
153f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f SQLITE_ERROR].</
15400 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
15410 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
15420 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f EX]] <dt>SQLITE_
15430 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c CONFIG_GETMUTEX<
15440 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
15450 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
15460 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e _GETMUTEX option
15470 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
15480 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a argument which.*
15490 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 * is a pointer t
154a0 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
154b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
154c0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 tex_methods] str
154d0 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 ucture. The.**
154e0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
154f0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 ethods].** struc
15500 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 ture is filled w
15510 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c ith the currentl
15520 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 y defined mutex
15530 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 routines.)^.** T
15540 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 his option can b
15550 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f e used to overlo
15560 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d ad the default m
15570 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a utex allocation.
15580 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 ** routines with
15590 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 a wrapper used
155a0 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 to track mutex u
155b0 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d sage for perform
155c0 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e ance.** profilin
155d0 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f g or testing, fo
155e0 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 r example. ^If
155f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
15600 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
15610 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
15620 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
15630 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
15640 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
15650 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 en.** the entire
15660 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 mutexing subsys
15670 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 tem is omitted f
15680 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e rom the build an
15690 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f d hence calls to
156a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
156b0 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 fig()] with the
156c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
156d0 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 TMUTEX configura
156e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c tion option will
156f0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
15700 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a TE_ERROR].</dd>.
15710 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
15720 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
15730 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
15740 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 FIG_LOOKASIDE</d
15750 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 t>.** <dd> ^(The
15760 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c SQLITE_CONFIG_L
15770 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 OOKASIDE option
15780 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 takes two argume
15790 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 nts that determi
157a0 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c ne.** the defaul
157b0 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 t size of lookas
157c0 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 ide memory on ea
157d0 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ch [database con
157e0 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 nection]..** The
157f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
15800 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f is the.** size o
15810 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 f each lookaside
15820 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 buffer slot and
15830 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 the second is t
15840 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
15850 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 slots allocated
15860 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 to each database
15870 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 connection.)^
15880 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ^(SQLITE_CONFIG_
15890 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 LOOKASIDE.** set
158a0 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 s the <i>default
158b0 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 </i> lookaside s
158c0 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 ize. The [SQLITE
158d0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
158e0 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 IDE].** option t
158f0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f o [sqlite3_db_co
15900 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 nfig()] can be u
15910 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 sed to change th
15920 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 e lookaside.** c
15930 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 onfiguration on
15940 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 individual conne
15950 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a ctions.)^ </dd>.
15960 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
15970 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 ONFIG_PCACHE2]]
15980 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
15990 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a G_PCACHE2</dt>.*
159a0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c * <dd> ^(The SQL
159b0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
159c0 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 E2 option takes
159d0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
159e0 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 t which is .** a
159f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b pointer to an [
15a00 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
15a10 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e ethods2] object.
15a20 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 This object sp
15a30 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 ecifies.** the i
15a40 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 nterface to a cu
15a50 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 stom page cache
15a60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 implementation.)
15a70 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b ^.** ^SQLite mak
15a80 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 es a copy of the
15a90 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 [sqlite3_pcache
15aa0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 _methods2] objec
15ab0 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b t.</dd>.**.** [[
15ac0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
15ad0 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 TPCACHE2]] <dt>S
15ae0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
15af0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 PCACHE2</dt>.**
15b00 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 <dd> ^(The SQLIT
15b10 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
15b20 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 HE2 option takes
15b30 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
15b40 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 nt which.** is a
15b50 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b pointer to an [
15b60 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
15b70 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e ethods2] object.
15b80 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 SQLite copies
15b90 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e of.** the curren
15ba0 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 t page cache imp
15bb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f lementation into
15bc0 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 that object.)^
15bd0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
15be0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d LITE_CONFIG_LOG]
15bf0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
15c00 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 FIG_LOG</dt>.**
15c10 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f <dd> The SQLITE_
15c20 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f CONFIG_LOG optio
15c30 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e n is used to con
15c40 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 figure the SQLit
15c50 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 e.** global [err
15c60 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 or log]..** (^Th
15c70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
15c80 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 LOG option takes
15c90 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 two arguments:
15ca0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a a pointer to a.*
15cb0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 * function with
15cc0 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 a call signature
15cd0 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 of void(*)(void
15ce0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 *,int,const char
15cf0 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f *), .** and a po
15d00 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e inter to void. ^
15d10 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 If the function
15d20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e pointer is not N
15d30 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e ULL, it is.** in
15d40 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 voked by [sqlite
15d50 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 3_log()] to proc
15d60 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 ess each logging
15d70 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 event. ^If the
15d80 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 .** function poi
15d90 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 nter is NULL, th
15da0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 e [sqlite3_log()
15db0 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f ] interface beco
15dc0 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 mes a no-op..**
15dd0 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 ^The void pointe
15de0 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 r that is the se
15df0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
15e00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c SQLITE_CONFIG_L
15e10 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 OG is.** passed
15e20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 through as the f
15e30 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
15e40 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f o the applicatio
15e50 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 n-defined logger
15e60 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 .** function whe
15e70 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 never that funct
15e80 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 ion is invoked.
15e90 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 ^The second par
15ea0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 ameter to.** the
15eb0 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e logger function
15ec0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
15ed0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
15ee0 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 r to the corresp
15ef0 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 onding.** [sqlit
15f00 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 e3_log()] call a
15f10 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 nd is intended t
15f20 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 o be a [result c
15f30 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 ode] or an.** [e
15f40 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
15f50 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 ode]. ^The thir
15f60 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 d parameter pass
15f70 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 ed to the logger
15f80 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 is.** log messa
15f90 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 ge after formatt
15fa0 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 ing via [sqlite3
15fb0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a _snprintf()]..**
15fc0 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 The SQLite logg
15fd0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 ing interface is
15fe0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 not reentrant;
15ff0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 the logger funct
16000 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 ion.** supplied
16010 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 by the applicati
16020 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f on must not invo
16030 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e ke any SQLite in
16040 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 terface..** In a
16050 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 multi-threaded
16060 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 application, the
16070 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
16080 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 ined logger.** f
16090 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 unction must be
160a0 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 threadsafe. </dd
160b0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
160c0 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 _CONFIG_URI]] <d
160d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
160e0 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 URI.** <dd>^(The
160f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 SQLITE_CONFIG_U
16100 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 RI option takes
16110 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
16120 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a t of type int..*
16130 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 * If non-zero, t
16140 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 hen URI handling
16150 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 is globally ena
16160 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 bled. If the par
16170 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a ameter is zero,.
16180 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 ** then URI hand
16190 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 ling is globally
161a0 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 disabled.)^ ^If
161b0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 URI handling is
161c0 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 globally.** ena
161d0 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 bled, all filena
161e0 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 mes passed to [s
161f0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
16200 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
16210 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
16220 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a _open16()] or.**
16230 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 specified as pa
16240 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 rt of [ATTACH] c
16250 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 ommands are inte
16260 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c rpreted as URIs,
16270 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f regardless.** o
16280 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
16290 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
162a0 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 N_URI] flag is s
162b0 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 et when the data
162c0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
162d0 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 on is opened. ^I
162e0 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 f it is globally
162f0 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e disabled, filen
16300 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 ames are.** only
16310 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
16320 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 URIs if the SQLI
16330 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 TE_OPEN_URI flag
16340 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 is set when the
16350 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
16360 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 nection is opene
16370 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c d. ^(By default,
16380 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 URI handling is
16390 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 globally.** dis
163a0 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 abled. The defau
163b0 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 lt value may be
163c0 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 changed by compi
163d0 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a ling with the.**
163e0 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 [SQLITE_USE_URI
163f0 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 ] symbol defined
16400 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 .)^.**.** [[SQLI
16410 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 TE_CONFIG_COVERI
16420 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 NG_INDEX_SCAN]]
16430 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
16440 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 G_COVERING_INDEX
16450 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 _SCAN.** <dd>^Th
16460 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16470 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 COVERING_INDEX_S
16480 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 CAN option takes
16490 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 a single intege
164a0 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 r.** argument wh
164b0 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 ich is interpret
164c0 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 ed as a boolean
164d0 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 in order to enab
164e0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a le or disable.**
164f0 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 the use of cove
16500 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 ring indices for
16510 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e full table scan
16520 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f s in the query o
16530 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 ptimizer..** ^Th
16540 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e e default settin
16550 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a g is determined.
16560 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 ** by the [SQLIT
16570 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 E_ALLOW_COVERING
16580 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d _INDEX_SCAN] com
16590 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
165a0 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 , or is "on".**
165b0 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d if that compile-
165c0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f time option is o
165d0 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 mitted..** The a
165e0 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c bility to disabl
165f0 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 e the use of cov
16600 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f ering indices fo
16610 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 r full table sca
16620 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 ns.** is because
16630 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c some incorrectl
16640 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 y coded legacy a
16650 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 pplications migh
16660 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a t malfunction.**
16670 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 when the optimi
16680 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 zation is enable
16690 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 d. Providing th
166a0 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 e ability to.**
166b0 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 disable the opti
166c0 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 mization allows
166d0 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 the older, buggy
166e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 application cod
166f0 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 e to work.** wit
16700 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e hout change even
16710 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 with newer vers
16720 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ions of SQLite..
16730 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
16740 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b ONFIG_PCACHE]] [
16750 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 [SQLITE_CONFIG_G
16760 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 ETPCACHE]].** <d
16770 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
16780 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 PCACHE and SQLIT
16790 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
167a0 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 HE.** <dd> These
167b0 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 options are obs
167c0 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 olete and should
167d0 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 not be used by
167e0 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 new code..** The
167f0 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 y are retained f
16800 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d or backwards com
16810 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 patibility but a
16820 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a re now no-ops..*
16830 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b * </dd>.**.** [[
16840 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 SQLITE_CONFIG_SQ
16850 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 LLOG]].** <dt>SQ
16860 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c LITE_CONFIG_SQLL
16870 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f OG.** <dd>This o
16880 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 ption is only av
16890 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 ailable if sqlit
168a0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
168b0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 th the.** [SQLIT
168c0 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d E_ENABLE_SQLLOG]
168d0 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d pre-processor m
168e0 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 acro defined. Th
168f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
16900 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 should.** be a
16910 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e pointer to a fun
16920 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f ction of type vo
16930 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
16940 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a te3*,const char*
16950 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 , int)..** The s
16960 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 econd should be
16970 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e of type (void*).
16980 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 The callback is
16990 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 invoked by the
169a0 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 library.** in th
169b0 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72 ree separate cir
169c0 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e cumstances, iden
169d0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61 tified by the va
169e0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 lue passed as th
169f0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 e.** fourth para
16a00 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f meter. If the fo
16a10 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
16a20 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 s 0, then the da
16a30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
16a40 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 n.** passed as t
16a50 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
16a60 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e nt has just been
16a70 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 opened. The thi
16a80 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 rd argument.** p
16a90 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 oints to a buffe
16aa0 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 r containing the
16ab0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 name of the mai
16ac0 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e n database file.
16ad0 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 If the.** fourt
16ae0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 h parameter is 1
16af0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 , then the SQL s
16b00 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 tatement that th
16b10 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
16b20 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 r.** points to h
16b30 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 as just been exe
16b40 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 cuted. Or, if th
16b50 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
16b60 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a er is 2, then.**
16b70 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 the connection
16b80 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 being passed as
16b90 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
16ba0 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c eter is being cl
16bb0 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 osed. The.** thi
16bc0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rd parameter is
16bd0 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 passed NULL In t
16be0 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 his case. An ex
16bf0 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 ample of using t
16c00 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 his.** configura
16c10 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 tion option can
16c20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 be seen in the "
16c30 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 test_sqllog.c" s
16c40 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a ource file in.**
16c50 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 the canonical S
16c60 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 QLite source tre
16c70 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b e.</dd>.**.** [[
16c80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d SQLITE_CONFIG_MM
16c90 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 AP_SIZE]].** <dt
16ca0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
16cb0 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e MAP_SIZE.** <dd>
16cc0 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d ^SQLITE_CONFIG_M
16cd0 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 MAP_SIZE takes t
16ce0 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 wo 64-bit intege
16cf0 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 r (sqlite3_int64
16d00 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 ) values.** that
16d10 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 are the default
16d20 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 mmap size limit
16d30 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 (the default se
16d40 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 tting for.** [PR
16d50 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 AGMA mmap_size])
16d60 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d and the maximum
16d70 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 allowed mmap si
16d80 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 ze limit..** ^Th
16d90 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e e default settin
16da0 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 g can be overrid
16db0 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 den by each data
16dc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
16dd0 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 using.** either
16de0 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 the [PRAGMA mmap
16df0 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 _size] command,
16e00 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a or by using the.
16e10 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c ** [SQLITE_FCNTL
16e20 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 _MMAP_SIZE] file
16e30 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 control. ^(The
16e40 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 maximum allowed
16e50 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 mmap size.** wi
16e60 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 ll be silently t
16e70 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 runcated if nece
16e80 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 ssary so that it
16e90 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 does not exceed
16ea0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d the.** compile-
16eb0 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 time maximum mma
16ec0 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 p size set by th
16ed0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 e.** [SQLITE_MAX
16ee0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 _MMAP_SIZE] comp
16ef0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e ile-time option.
16f00 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 )^.** ^If either
16f10 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 argument to thi
16f20 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 s option is nega
16f30 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 tive, then that
16f40 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 argument is.** c
16f50 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f hanged to its co
16f60 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 mpile-time defau
16f70 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 lt..**.** [[SQLI
16f80 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f TE_CONFIG_WIN32_
16f90 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 HEAPSIZE]].** <d
16fa0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
16fb0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a WIN32_HEAPSIZE.*
16fc0 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 * <dd>^The SQLIT
16fd0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 E_CONFIG_WIN32_H
16fe0 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 EAPSIZE option i
16ff0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 s only available
17000 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a if SQLite is.**
17010 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 compiled for Wi
17020 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b ndows with the [
17030 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c SQLITE_WIN32_MAL
17040 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 LOC] pre-process
17050 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 or macro.** defi
17060 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e ned. ^SQLITE_CON
17070 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 FIG_WIN32_HEAPSI
17080 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 ZE takes a 32-bi
17090 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 t unsigned integ
170a0 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 er value.** that
170b0 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 6d specifies the m
170c0 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 aximum size of t
170d0 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70 2e he created heap.
170e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
170f0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 CONFIG_PCACHE_HD
17100 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c RSZ]].** <dt>SQL
17110 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
17120 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e E_HDRSZ.** <dd>^
17130 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
17140 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f G_PCACHE_HDRSZ o
17150 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
17160 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 ngle parameter w
17170 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 hich.** is a poi
17180 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
17190 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e er and writes in
171a0 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 to that integer
171b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 the number of ex
171c0 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 tra.** bytes per
171d0 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20 66 page required f
171e0 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 or each page in
171f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
17200 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 AGECACHE]..** Th
17210 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 e amount of extr
17220 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 a space required
17230 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 can change depe
17240 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d nding on the com
17250 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 piler,.** target
17260 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 platform, and S
17270 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a QLite version..*
17280 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
17290 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 NFIG_PMASZ]].**
172a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
172b0 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e G_PMASZ.** <dd>^
172c0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
172d0 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 G_PMASZ option t
172e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 akes a single pa
172f0 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a rameter which.**
17300 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 is an unsigned
17310 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 integer and sets
17320 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d the "Minimum PM
17330 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 A Size" for the
17340 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a multithreaded.**
17350 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 sorter to that
17360 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 integer. The de
17370 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d fault minimum PM
17380 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 A Size is set by
17390 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
173a0 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f SORTER_PMASZ] co
173b0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
173c0 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 n. New threads
173d0 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 are launched.**
173e0 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 to help with sor
173f0 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 t operations whe
17400 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 n multithreaded
17410 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e sorting.** is en
17420 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 abled (using the
17430 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 [PRAGMA threads
17440 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 ] command) and t
17450 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e he amount of con
17460 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f tent.** to be so
17470 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68 65 rted exceeds the
17480 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 page size times
17490 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 the minimum of
174a0 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 the.** [PRAGMA c
174b0 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 ache_size] setti
174c0 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 ng and this valu
174d0 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 e..**.** [[SQLIT
174e0 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e E_CONFIG_STMTJRN
174f0 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 L_SPILL]].** <dt
17500 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
17510 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a TMTJRNL_SPILL.**
17520 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 <dd>^The SQLITE
17530 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c _CONFIG_STMTJRNL
17540 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 _SPILL option ta
17550 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 kes a single par
17560 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 ameter which.**
17570 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 becomes the [sta
17580 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 tement journal]
17590 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 spill-to-disk th
175a0 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 reshold. .** [S
175b0 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c tatement journal
175c0 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e 20 6d s] are held in m
175d0 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68 65 69 emory until thei
175e0 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74 65 73 r size (in bytes
175f0 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74 68 69 ).** exceeds thi
17600 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 s threshold, at
17610 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68 65 79 which point they
17620 20 61 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20 are written to
17630 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 disk..** Or if t
17640 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69 73 20 he threshold is
17650 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f -1, statement jo
17660 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77 61 79 urnals are alway
17670 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 s held.** exclus
17680 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e ively in memory.
17690 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 .** Since many s
176a0 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c tatement journal
176b0 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65 20 6c s never become l
176c0 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20 74 68 arge, setting th
176d0 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 e spill.** thres
176e0 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75 65 20 hold to a value
176f0 73 75 63 68 20 61 73 20 36 34 4b 69 42 20 63 61 such as 64KiB ca
17700 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75 63 65 n greatly reduce
17710 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a the amount of.*
17720 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64 20 74 * I/O required t
17730 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74 65 6d o support statem
17740 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a ent rollback..**
17750 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c The default val
17760 75 65 20 66 6f 72 20 74 68 69 73 20 73 65 74 74 ue for this sett
17770 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 ing is controlle
17780 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c d by the.** [SQL
17790 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 ITE_STMTJRNL_SPI
177a0 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 LL] compile-time
177b0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c option..** </dl
177c0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
177d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
177e0 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e ETHREAD 1 /* n
177f0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 il */.#define SQ
17800 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
17810 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 ITHREAD 2 /*
17820 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nil */.#define S
17830 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 QLITE_CONFIG_SER
17840 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a IALIZED 3 /*
17850 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nil */.#define
17860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
17870 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f LLOC 4 /
17880 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 * sqlite3_mem_me
17890 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e thods* */.#defin
178a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
178b0 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 GETMALLOC 5
178c0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f /* sqlite3_mem_
178d0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
178e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
178f0 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 G_SCRATCH
17900 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 6 /* No longer
17910 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 used */.#define
17920 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
17930 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f GECACHE 7 /
17940 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c * void*, int sz,
17950 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e int N */.#defin
17960 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
17970 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 HEAP 8
17980 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e /* void*, int n
17990 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f Byte, int min */
179a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
179b0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
179c0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 9 /* boole
179d0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 an */.#define SQ
179e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
179f0 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 X 10 /*
17a00 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
17a10 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e thods* */.#defin
17a20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
17a30 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 GETMUTEX 11
17a40 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 /* sqlite3_mute
17a50 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a x_methods* */./*
17a60 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 previously SQLI
17a70 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 TE_CONFIG_CHUNKA
17a80 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 LLOC 12 which is
17a90 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 now unused. */
17aa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17ab0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
17ac0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 13 /* int i
17ad0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 nt */.#define SQ
17ae0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
17af0 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 HE 14 /*
17b00 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 no-op */.#define
17b10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
17b20 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 ETPCACHE 15
17b30 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 /* no-op */.#def
17b40 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
17b50 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 G_LOG 1
17b60 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 6 /* xFunc, voi
17b70 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 d* */.#define SQ
17b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 LITE_CONFIG_URI
17b90 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 17 /*
17ba0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 int */.#define S
17bb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
17bc0 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a CHE2 18 /*
17bd0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f sqlite3_pcache_
17be0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 methods2* */.#de
17bf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
17c00 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 IG_GETPCACHE2
17c10 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 19 /* sqlite3_p
17c20 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 cache_methods2*
17c30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17c40 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e E_CONFIG_COVERIN
17c50 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 G_INDEX_SCAN 20
17c60 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 /* int */.#defi
17c70 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
17c80 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 _SQLLOG 21
17c90 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f /* xSqllog, vo
17ca0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 id* */.#define S
17cb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 QLITE_CONFIG_MMA
17cc0 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a P_SIZE 22 /*
17cd0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 sqlite3_int64,
17ce0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f sqlite3_int64 */
17cf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17d00 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 CONFIG_WIN32_HEA
17d10 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f PSIZE 23 /
17d20 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 * int nByte */.#
17d30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
17d40 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 NFIG_PCACHE_HDRS
17d50 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 Z 24 /*
17d60 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 int *psz */.#def
17d70 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
17d80 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 G_PMASZ
17d90 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 25 /* uns
17da0 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 igned int szPma
17db0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17dc0 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e E_CONFIG_STMTJRN
17dd0 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20 L_SPILL 26
17de0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f /* int nByte */
17df0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17e00 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c CONFIG_SMALL_MAL
17e10 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20 20 2f LOC 27 /
17e20 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 0a 2f 2a * boolean */../*
17e30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 .** CAPI3REF: Da
17e40 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
17e50 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 n Configuration
17e60 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 Options.**.** Th
17e70 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
17e80 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 e the available
17e90 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 integer configur
17ea0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 ation options th
17eb0 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 at.** can be pas
17ec0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
17ed0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 d argument to th
17ee0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f e [sqlite3_db_co
17ef0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
17f00 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e e..**.** New con
17f10 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
17f20 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ns may be added
17f30 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
17f40 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
17f50 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 Existing config
17f60 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
17f70 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 might be discont
17f80 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 inued. Applicat
17f90 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 ions.** should c
17fa0 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 heck the return
17fb0 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 code from [sqlit
17fc0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
17fd0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 to make sure tha
17fe0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f t.** the call wo
17ff0 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c rked. ^The [sql
18000 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
18010 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c ] interface will
18020 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e return a.** non
18030 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 -zero [error cod
18040 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 e] if a disconti
18050 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 nued or unsuppor
18060 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ted configuratio
18070 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 n option.** is i
18080 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 nvoked..**.** <d
18090 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 l>.** <dt>SQLITE
180a0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
180b0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e IDE</dt>.** <dd>
180c0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 ^This option ta
180d0 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 kes three additi
180e0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 onal arguments t
180f0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 hat determine th
18100 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 e .** [lookaside
18110 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
18120 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e r] configuration
18130 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 for the [databa
18140 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a se connection]..
18150 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
18160 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 gument (the thir
18170 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b d parameter to [
18180 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
18190 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 g()] is a.** poi
181a0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 nter to a memory
181b0 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 buffer to use f
181c0 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d or lookaside mem
181d0 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ory..** ^The fir
181e0 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 st argument afte
181f0 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 r the SQLITE_DBC
18200 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
18210 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e verb.** may be N
18220 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 ULL in which cas
18230 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c e SQLite will al
18240 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f locate the.** lo
18250 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 okaside buffer i
18260 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c tself using [sql
18270 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 ite3_malloc()].
18280 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 ^The second argu
18290 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 ment is the.** s
182a0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b ize of each look
182b0 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f aside buffer slo
182c0 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 t. ^The third a
182d0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e rgument is the n
182e0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 umber of.** slot
182f0 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 s. The size of
18300 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 the buffer in th
18310 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
18320 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 must be greater
18330 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 than.** or equa
18340 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 l to the product
18350 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 of the second a
18360 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e nd third argumen
18370 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a ts. The buffer.
18380 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e ** must be align
18390 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 ed to an 8-byte
183a0 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 boundary. ^If t
183b0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
183c0 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f nt to.** SQLITE_
183d0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
183e0 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 DE is not a mult
183f0 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 iple of 8, it is
18400 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 internally.** r
18410 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 ounded down to t
18420 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 he next smaller
18430 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 multiple of 8.
18440 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 ^(The lookaside
18450 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 memory.** config
18460 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 uration for a da
18470 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
18480 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 n can only be ch
18490 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a anged when that.
184a0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 ** connection is
184b0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 not currently u
184c0 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d sing lookaside m
184d0 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 emory, or in oth
184e0 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e er words.** when
184f0 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 the "current va
18500 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 lue" returned by
18510 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f .** [sqlite3_db_
18520 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 status](D,[SQLIT
18530 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
18540 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f DE],...) is zero
18550 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 ..** Any attempt
18560 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c to change the l
18570 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
18580 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 configuration wh
18590 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 en lookaside.**
185a0 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 memory is in use
185b0 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 leaves the conf
185c0 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e iguration unchan
185d0 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ged and returns
185e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 .** [SQLITE_BUSY
185f0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ].)^</dd>.**.**
18600 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e <dt>SQLITE_DBCON
18610 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c FIG_ENABLE_FKEY<
18620 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
18630 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 is option is use
18640 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 d to enable or d
18650 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 isable the enfor
18660 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f cement of.** [fo
18670 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 reign key constr
18680 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 aints]. There s
18690 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 hould be two add
186a0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
186b0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 s..** The first
186c0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 argument is an i
186d0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 nteger which is
186e0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 0 to disable FK
186f0 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 enforcement,.**
18700 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 positive to enab
18710 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e le FK enforcemen
18720 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f t or negative to
18730 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 leave FK enforc
18740 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 ement.** unchang
18750 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ed. The second
18760 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
18770 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
18780 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a eger into which.
18790 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 ** is written 0
187a0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 or 1 to indicate
187b0 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f whether FK enfo
187c0 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f rcement is off o
187d0 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e r on.** followin
187e0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 g this call. Th
187f0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
18800 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c er may be a NULL
18810 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 pointer, in.**
18820 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 which case the F
18830 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 K enforcement se
18840 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 tting is not rep
18850 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 orted back. </dd
18860 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
18870 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
18880 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a LE_TRIGGER</dt>.
18890 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
188a0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
188b0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
188c0 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 e [CREATE TRIGGE
188d0 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a R | triggers]..*
188e0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 * There should b
188f0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c e two additional
18900 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 arguments..** T
18910 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
18920 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 t is an integer
18930 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 which is 0 to di
18940 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a sable triggers,.
18950 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 ** positive to e
18960 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f nable triggers o
18970 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 r negative to le
18980 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 ave the setting
18990 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 unchanged..** Th
189a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
189b0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 er is a pointer
189c0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e to an integer in
189d0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 to which.** is w
189e0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f ritten 0 or 1 to
189f0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 indicate whethe
18a00 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 r triggers are d
18a10 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c isabled or enabl
18a20 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ed.** following
18a30 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 this call. The
18a40 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
18a50 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 may be a NULL p
18a60 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 ointer, in.** wh
18a70 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 ich case the tri
18a80 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 gger setting is
18a90 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 not reported bac
18aa0 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c k. </dd>.**.** <
18ab0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
18ac0 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 IG_ENABLE_FTS3_T
18ad0 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a OKENIZER</dt>.**
18ae0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
18af0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e on is used to en
18b00 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 able or disable
18b10 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 the two-argument
18b20 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 .** version of t
18b30 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a he [fts3_tokeniz
18b40 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 er()] function w
18b50 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 hich is part of
18b60 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 the.** [FTS3] fu
18b70 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 ll-text search e
18b80 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e ngine extension.
18b90 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 .** There should
18ba0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e be two addition
18bb0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a al arguments..**
18bc0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
18bd0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ent is an intege
18be0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 r which is 0 to
18bf0 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b disable fts3_tok
18c00 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 enizer() or.** p
18c10 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c ositive to enabl
18c20 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 e fts3_tokenizer
18c30 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 () or negative t
18c40 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 o leave the sett
18c50 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 ing.** unchanged
18c60 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
18c70 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
18c80 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
18c90 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a eger into which.
18ca0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 ** is written 0
18cb0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 or 1 to indicate
18cc0 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f whether fts3_to
18cd0 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 kenizer is disab
18ce0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a led or enabled.*
18cf0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 * following this
18d00 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f call. The seco
18d10 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 nd parameter may
18d20 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 be a NULL point
18d30 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 er, in.** which
18d40 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 case the new set
18d50 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f ting is not repo
18d60 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e rted back. </dd>
18d70 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
18d80 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
18d90 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e E_LOAD_EXTENSION
18da0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
18db0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 his option is us
18dc0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 ed to enable or
18dd0 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c disable the [sql
18de0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 ite3_load_extens
18df0 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 ion()].** interf
18e00 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c ace independentl
18e10 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 y of the [load_e
18e20 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 xtension()] SQL
18e30 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 function..** The
18e40 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 [sqlite3_enable
18e50 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
18e60 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f )] API enables o
18e70 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 r disables both
18e80 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 the.** C-API [sq
18e90 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e lite3_load_exten
18ea0 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 sion()] and the
18eb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f SQL function [lo
18ec0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e ad_extension()].
18ed0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 .** There should
18ee0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e be two addition
18ef0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a al arguments..**
18f00 20 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 When the first
18f10 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 argument to this
18f20 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c interface is 1,
18f30 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 then only the C
18f40 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c -API is.** enabl
18f50 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 ed and the SQL f
18f60 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 unction remains
18f70 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 disabled. If th
18f80 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
18f90 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 to.** this inte
18fa0 72 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e rface is 0, then
18fb0 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 both the C-API
18fc0 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 and the SQL func
18fd0 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 tion are disable
18fe0 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 d..** If the fir
18ff0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d st argument is -
19000 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 1, then no chang
19010 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 es are made to s
19020 74 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 tate of either t
19030 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 he.** C-API or t
19040 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e he SQL function.
19050 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 .** The second p
19060 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f arameter is a po
19070 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
19080 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a ger into which.*
19090 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f * is written 0 o
190a0 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 r 1 to indicate
190b0 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 whether [sqlite3
190c0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
190d0 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 )] interface.**
190e0 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 is disabled or e
190f0 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 nabled following
19100 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 this call. The
19110 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
19120 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 r may.** be a NU
19130 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 LL pointer, in w
19140 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 hich case the ne
19150 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 w setting is not
19160 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a reported back..
19170 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ** </dd>.**.** <
19180 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
19190 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 IG_MAINDBNAME</d
191a0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
191b0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 option is used
191c0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 to change the na
191d0 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 me of the "main"
191e0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 database.** sch
191f0 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 ema. ^The sole
19200 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f argument is a po
19210 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 inter to a const
19220 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a ant UTF8 string.
19230 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 ** which will be
19240 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 come the new sch
19250 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 ema name in plac
19260 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 e of "main". ^S
19270 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f QLite.** does no
19280 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 t make a copy of
19290 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 the new main sc
192a0 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 hema name string
192b0 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 , so the applica
192c0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 tion.** must ens
192d0 75 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67 ure that the arg
192e0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 ument passed int
192f0 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 o this DBCONFIG
19300 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e option is unchan
19310 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 ged.** until aft
19320 65 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 er the database
19330 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 connection close
19340 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a s..** </dd>.**.*
19350 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 * <dt>SQLITE_DBC
19360 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e ONFIG_NO_CKPT_ON
19370 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c _CLOSE</dt>.** <
19380 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 dd> Usually, whe
19390 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 6e 20 n a database in
193a0 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 wal mode is clos
193b0 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 20 66 ed or detached f
193c0 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 rom a .** databa
193d0 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 se handle, SQLit
193e0 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 69 73 e checks if this
193f0 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 will mean that
19400 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f there are now no
19410 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 .** connections
19420 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 at all to the d
19430 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 atabase. If so,
19440 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68 it performs a ch
19450 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 eckpoint .** ope
19460 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c ration before cl
19470 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 osing the connec
19480 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f tion. This optio
19490 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f n may be used to
194a0 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69 .** override thi
194b0 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65 s behaviour. The
194c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
194d0 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 passed to this
194e0 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 operation.** is
194f0 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e an integer - non
19500 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 -zero to disable
19510 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d checkpoints-on-
19520 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 close, or zero (
19530 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 the.** default)
19540 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20 to enable them.
19550 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
19560 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 eter is a pointe
19570 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a r to an integer.
19580 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 ** into which is
19590 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 written 0 or 1
195a0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 to indicate whet
195b0 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d her checkpoints-
195c0 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 on-close.** have
195d0 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d been disabled -
195e0 20 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e 0 if they are n
195f0 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69 ot disabled, 1 i
19600 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c f they are..** <
19610 2f 64 64 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 /dd>.** <dt>SQLI
19620 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
19630 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a 2a 2a 20 LE_QPSG</dt>.**
19640 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 <dd>^(The SQLITE
19650 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
19660 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20 61 63 74 _QPSG option act
19670 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 74 69 ivates or deacti
19680 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 5b 71 75 vates.** the [qu
19690 65 72 79 20 70 6c 61 6e 6e 65 72 20 73 74 61 62 ery planner stab
196a0 69 6c 69 74 79 20 67 75 61 72 61 6e 74 65 65 5d ility guarantee]
196b0 20 28 51 50 53 47 29 2e 20 20 57 68 65 6e 20 74 (QPSG). When t
196c0 68 65 20 51 50 53 47 20 69 73 20 61 63 74 69 76 he QPSG is activ
196d0 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 53 e,.** a single S
196e0 51 4c 20 71 75 65 72 79 20 73 74 61 74 65 6d 65 QL query stateme
196f0 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75 nt will always u
19700 73 65 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f se the same algo
19710 72 69 74 68 6d 20 72 65 67 61 72 64 6c 65 73 73 rithm regardless
19720 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73 20 6f 66 .** of values of
19730 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 [bound paramete
19740 72 73 5d 2e 29 5e 20 54 68 65 20 51 50 53 47 20 rs].)^ The QPSG
19750 64 69 73 61 62 6c 65 73 20 73 6f 6d 65 20 71 75 disables some qu
19760 65 72 79 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e ery optimization
19770 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f 6b 20 61 s.** that look a
19780 74 20 74 68 65 20 76 61 6c 75 65 73 20 6f 66 20 t the values of
19790 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 bound parameters
197a0 2c 20 77 68 69 63 68 20 63 61 6e 20 6d 61 6b 65 , which can make
197b0 20 73 6f 6d 65 20 71 75 65 72 69 65 73 0a 2a 2a some queries.**
197c0 20 73 6c 6f 77 65 72 2e 20 20 42 75 74 20 74 68 slower. But th
197d0 65 20 51 50 53 47 20 68 61 73 20 74 68 65 20 61 e QPSG has the a
197e0 64 76 61 6e 74 61 67 65 20 6f 66 20 6d 6f 72 65 dvantage of more
197f0 20 70 72 65 64 69 63 74 61 62 6c 65 20 62 65 68 predictable beh
19800 61 76 69 6f 72 2e 20 20 57 69 74 68 0a 2a 2a 20 avior. With.**
19810 74 68 65 20 51 50 53 47 20 61 63 74 69 76 65 2c the QPSG active,
19820 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 SQLite will alw
19830 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65 ays use the same
19840 20 71 75 65 72 79 20 70 6c 61 6e 20 69 6e 20 74 query plan in t
19850 68 65 20 66 69 65 6c 64 20 61 73 0a 2a 2a 20 77 he field as.** w
19860 61 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 as used during t
19870 65 73 74 69 6e 67 20 69 6e 20 74 68 65 20 6c 61 esting in the la
19880 62 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c b..** </dd>.** <
19890 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
198a0 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 3c 2f IG_TRIGGER_EQP</
198b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42 79 20 64 dt>.** <dd> By d
198c0 65 66 61 75 6c 74 2c 20 74 68 65 20 6f 75 74 70 efault, the outp
198d0 75 74 20 6f 66 20 45 58 50 4c 41 49 4e 20 51 55 ut of EXPLAIN QU
198e0 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d 61 6e 64 ERY PLAN command
198f0 73 20 64 6f 65 73 20 6e 6f 74 20 0a 2a 2a 20 69 s does not .** i
19900 6e 63 6c 75 64 65 20 6f 75 74 70 75 74 20 66 6f nclude output fo
19910 72 20 61 6e 79 20 6f 70 65 72 61 74 69 6f 6e 73 r any operations
19920 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 72 performed by tr
19930 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 igger programs.
19940 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 This.** option i
19950 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 s used to set or
19960 20 63 6c 65 61 72 20 28 74 68 65 20 64 65 66 61 clear (the defa
19970 75 6c 74 29 20 61 20 66 6c 61 67 20 74 68 61 74 ult) a flag that
19980 20 67 6f 76 65 72 6e 73 20 74 68 69 73 0a 2a 2a governs this.**
19990 20 62 65 68 61 76 69 6f 72 2e 20 54 68 65 20 66 behavior. The f
199a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70 irst parameter p
199b0 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70 assed to this op
199c0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 69 6e eration is an in
199d0 74 65 67 65 72 20 2d 0a 2a 2a 20 6e 6f 6e 2d 7a teger -.** non-z
199e0 65 72 6f 20 74 6f 20 65 6e 61 62 6c 65 20 6f 75 ero to enable ou
199f0 74 70 75 74 20 66 6f 72 20 74 72 69 67 67 65 72 tput for trigger
19a00 20 70 72 6f 67 72 61 6d 73 2c 20 6f 72 20 7a 65 programs, or ze
19a10 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 69 74 ro to disable it
19a20 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
19a30 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
19a40 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
19a50 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 20 eger into which
19a60 69 73 20 77 72 69 74 74 65 6e 20 0a 2a 2a 20 30 is written .** 0
19a70 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 or 1 to indicat
19a80 65 20 77 68 65 74 68 65 72 20 6f 75 74 70 75 74 e whether output
19a90 2d 66 6f 72 2d 74 72 69 67 67 65 72 73 20 68 61 -for-triggers ha
19aa0 73 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 s been disabled
19ab0 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74 20 69 73 - 0 if .** it is
19ac0 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 not disabled, 1
19ad0 20 69 66 20 69 74 20 69 73 2e 20 20 0a 2a 2a 20 if it is. .**
19ae0 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a </dd>.** </dl>.*
19af0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
19b00 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 _DBCONFIG_MAINDB
19b10 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 NAME
19b20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68 1000 /* const ch
19b30 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ar* */.#define S
19b40 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
19b50 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 20 OOKASIDE
19b60 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 1001 /* voi
19b70 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 d* int int */.#d
19b80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 efine SQLITE_DBC
19b90 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 ONFIG_ENABLE_FKE
19ba0 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30 32 Y 1002
19bb0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a /* int int* */.
19bc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
19bd0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 BCONFIG_ENABLE_T
19be0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31 30 RIGGER 10
19bf0 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 03 /* int int* *
19c00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
19c10 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
19c20 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 _FTS3_TOKENIZER
19c30 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 1004 /* int int*
19c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
19c50 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
19c60 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f LE_LOAD_EXTENSIO
19c70 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e N 1005 /* int in
19c80 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t* */.#define SQ
19c90 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f LITE_DBCONFIG_NO
19ca0 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 _CKPT_ON_CLOSE
19cb0 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20 1006 /* int
19cc0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int* */.#define
19cd0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
19ce0 45 4e 41 42 4c 45 5f 51 50 53 47 20 20 20 20 20 ENABLE_QPSG
19cf0 20 20 20 20 20 20 31 30 30 37 20 2f 2a 20 69 6e 1007 /* in
19d00 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e t int* */.#defin
19d10 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
19d20 47 5f 54 52 49 47 47 45 52 5f 45 51 50 20 20 20 G_TRIGGER_EQP
19d30 20 20 20 20 20 20 20 20 31 30 30 38 20 2f 2a 20 1008 /*
19d40 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 int int* */.#def
19d50 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e ine SQLITE_DBCON
19d60 46 49 47 5f 4d 41 58 20 20 20 20 20 20 20 20 20 FIG_MAX
19d70 20 20 20 20 20 20 20 20 20 20 31 30 30 38 20 2f 1008 /
19d80 2a 20 4c 61 72 67 65 73 74 20 44 42 43 4f 4e 46 * Largest DBCONF
19d90 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 IG */../*.** CAP
19da0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 I3REF: Enable Or
19db0 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 Disable Extende
19dc0 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a d Result Codes.*
19dd0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
19de0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 3.**.** ^The sql
19df0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
19e00 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 sult_codes() rou
19e10 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 tine enables or
19e20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 disables the.**
19e30 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
19e40 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 codes] feature
19e50 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 of SQLite. ^The
19e60 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a extended result.
19e70 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 ** codes are dis
19e80 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
19e90 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 for historical
19ea0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a compatibility..*
19eb0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 /.int sqlite3_ex
19ec0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
19ed0 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e des(sqlite3*, in
19ee0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a t onoff);../*.**
19ef0 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 CAPI3REF: Last
19f00 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 Insert Rowid.**
19f10 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
19f20 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 **.** ^Each entr
19f30 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 y in most SQLite
19f40 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 tables (except
19f50 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 for [WITHOUT ROW
19f60 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 ID] tables).** h
19f70 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 as a unique 64-b
19f80 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 it signed.** int
19f90 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 eger key called
19fa0 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f the [ROWID | "ro
19fb0 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 wid"]. ^The rowi
19fc0 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 d is always avai
19fd0 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 lable.** as an u
19fe0 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e ndeclared column
19ff0 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 named ROWID, OI
1a000 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 D, or _ROWID_ as
1a010 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a long as those.*
1a020 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 * names are not
1a030 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 also used by exp
1a040 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 licitly declared
1a050 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a columns. ^If.**
1a060 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 the table has a
1a070 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 column of type
1a080 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 [INTEGER PRIMARY
1a090 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 KEY] then that
1a0a0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f column.** is ano
1a0b0 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 ther alias for t
1a0c0 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 he rowid..**.**
1a0d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 ^The sqlite3_las
1a0e0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 t_insert_rowid(D
1a0f0 29 20 69 6e 74 65 72 66 61 63 65 20 75 73 75 61 ) interface usua
1a100 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 lly returns the
1a110 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20 74 68 [rowid] of.** th
1a120 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 e most recent su
1a130 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
1a140 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 ] into a rowid t
1a150 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c able or [virtual
1a160 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 table].** on da
1a170 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1a180 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73 20 69 6e n D. ^Inserts in
1a190 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 to [WITHOUT ROWI
1a1a0 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f D] tables are no
1a1b0 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e 20 5e t.** recorded. ^
1a1c0 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c If no successful
1a1d0 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 [INSERT]s into
1a1e0 72 6f 77 69 64 20 74 61 62 6c 65 73 20 68 61 76 rowid tables hav
1a1f0 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 e ever occurred
1a200 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74 61 62 .** on the datab
1a210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 ase connection D
1a220 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c , then sqlite3_l
1a230 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
1a240 28 44 29 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 (D) returns .**
1a250 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 zero..**.** As w
1a260 65 6c 6c 20 61 73 20 62 65 69 6e 67 20 73 65 74 ell as being set
1a270 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 automatically a
1a280 73 20 72 6f 77 73 20 61 72 65 20 69 6e 73 65 72 s rows are inser
1a290 74 65 64 20 69 6e 74 6f 20 64 61 74 61 62 61 73 ted into databas
1a2a0 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74 68 65 e.** tables, the
1a2b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
1a2c0 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e by this function
1a2d0 20 6d 61 79 20 62 65 20 73 65 74 20 65 78 70 6c may be set expl
1a2e0 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b 73 71 icitly by.** [sq
1a2f0 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 lite3_set_last_i
1a300 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a nsert_rowid()].*
1a310 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74 75 61 *.** Some virtua
1a320 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e l table implemen
1a330 74 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e 53 45 tations may INSE
1a340 52 54 20 72 6f 77 73 20 69 6e 74 6f 20 72 6f 77 RT rows into row
1a350 69 64 20 74 61 62 6c 65 73 20 61 73 0a 2a 2a 20 id tables as.**
1a360 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74 74 69 part of committi
1a370 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e ng a transaction
1a380 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73 68 20 (e.g. to flush
1a390 64 61 74 61 20 61 63 63 75 6d 75 6c 61 74 65 64 data accumulated
1a3a0 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 74 6f in memory.** to
1a3b0 20 64 69 73 6b 29 2e 20 49 6e 20 74 68 69 73 20 disk). In this
1a3c0 63 61 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 case subsequent
1a3d0 63 61 6c 6c 73 20 74 6f 20 74 68 69 73 20 66 75 calls to this fu
1a3e0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 20 74 68 nction return th
1a3f0 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73 6f 63 e rowid.** assoc
1a400 69 61 74 65 64 20 77 69 74 68 20 74 68 65 73 65 iated with these
1a410 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45 52 54 internal INSERT
1a420 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77 68 69 operations, whi
1a430 63 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a 2a 20 ch leads to .**
1a440 75 6e 69 6e 74 75 69 74 69 76 65 20 72 65 73 75 unintuitive resu
1a450 6c 74 73 2e 20 56 69 72 74 75 61 6c 20 74 61 62 lts. Virtual tab
1a460 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
1a470 6e 73 20 74 68 61 74 20 64 6f 20 77 72 69 74 65 ns that do write
1a480 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74 61 62 to rowid.** tab
1a490 6c 65 73 20 69 6e 20 74 68 69 73 20 77 61 79 20 les in this way
1a4a0 63 61 6e 20 61 76 6f 69 64 20 74 68 69 73 20 70 can avoid this p
1a4b0 72 6f 62 6c 65 6d 20 62 79 20 72 65 73 74 6f 72 roblem by restor
1a4c0 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c ing the original
1a4d0 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c 75 65 .** rowid value
1a4e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
1a4f0 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f set_last_insert_
1a500 72 6f 77 69 64 28 29 5d 20 62 65 66 6f 72 65 20 rowid()] before
1a510 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20 63 6f returning .** co
1a520 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20 75 73 65 ntrol to the use
1a530 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e r..**.** ^(If an
1a540 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 [INSERT] occurs
1a550 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 within a trigge
1a560 72 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 r then this rout
1a570 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72 65 74 ine will .** ret
1a580 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 urn the [rowid]
1a590 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 20 of the inserted
1a5a0 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 row as long as t
1a5b0 68 65 20 74 72 69 67 67 65 72 20 69 73 20 0a 2a he trigger is .*
1a5c0 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63 65 20 * running. Once
1a5d0 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 the trigger prog
1a5e0 72 61 6d 20 65 6e 64 73 2c 20 74 68 65 20 76 61 ram ends, the va
1a5f0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a lue returned .**
1a600 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 by this routine
1a610 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 reverts to what
1a620 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 it was before t
1a630 68 65 20 74 72 69 67 67 65 72 20 77 61 73 20 66 he trigger was f
1a640 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 ired.)^.**.** ^A
1a650 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 n [INSERT] that
1a660 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 fails due to a c
1a670 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
1a680 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 ion is not a.**
1a690 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 successful [INSE
1a6a0 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 RT] and does not
1a6b0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 change the valu
1a6c0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 e returned by th
1a6d0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 is.** routine.
1a6e0 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 ^Thus INSERT OR
1a6f0 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 FAIL, INSERT OR
1a700 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f IGNORE, INSERT O
1a710 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 R ROLLBACK,.** a
1a720 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f nd INSERT OR ABO
1a730 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 RT make no chang
1a740 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e es to the return
1a750 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a value of this.*
1a760 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 * routine when t
1a770 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 heir insertion f
1a780 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e ails. ^(When IN
1a790 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a SERT OR REPLACE.
1a7a0 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 ** encounters a
1a7b0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
1a7c0 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f tion, it does no
1a7d0 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 t fail. The.**
1a7e0 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 INSERT continues
1a7f0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 to completion a
1a800 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f fter deleting ro
1a810 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a ws that caused.*
1a820 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 * the constraint
1a830 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 problem so INSE
1a840 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 RT OR REPLACE wi
1a850 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 ll always change
1a860 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 .** the return v
1a870 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 alue of this int
1a880 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 erface.)^.**.**
1a890 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 ^For the purpose
1a8a0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e s of this routin
1a8b0 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 e, an [INSERT] i
1a8c0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a s considered to.
1a8d0 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c ** be successful
1a8e0 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 even if it is s
1a8f0 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c ubsequently roll
1a900 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 ed back..**.** T
1a910 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 his function is
1a920 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 accessible to SQ
1a930 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 L statements via
1a940 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e the.** [last_in
1a950 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c sert_rowid() SQL
1a960 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a function]..**.*
1a970 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 * If a separate
1a980 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 thread performs
1a990 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f a new [INSERT] o
1a9a0 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 n the same.** da
1a9b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1a9c0 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c n while the [sql
1a9d0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
1a9e0 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e _rowid()].** fun
1a9f0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
1aa00 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 and thus change
1aa10 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 s the last inser
1aa20 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 t [rowid],.** th
1aa30 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 en the value ret
1aa40 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
1aa50 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
1aa60 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 wid()] is.** unp
1aa70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d redictable and m
1aa80 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 ight not equal e
1aa90 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 ither the old or
1aaa0 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 the new.** last
1aab0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e insert [rowid].
1aac0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 .*/.sqlite3_int6
1aad0 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 4 sqlite3_last_i
1aae0 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 nsert_rowid(sqli
1aaf0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
1ab00 50 49 33 52 45 46 3a 20 53 65 74 20 74 68 65 20 PI3REF: Set the
1ab10 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 Last Insert Rowi
1ab20 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45 54 48 d value..** METH
1ab30 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
1ab40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 * The sqlite3_se
1ab50 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f t_last_insert_ro
1ab60 77 69 64 28 44 2c 20 52 29 20 6d 65 74 68 6f 64 wid(D, R) method
1ab70 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 70 70 6c allows the appl
1ab80 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 73 65 ication to.** se
1ab90 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 t the value retu
1aba0 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 rned by calling
1abb0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
1abc0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 74 6f 20 ert_rowid(D) to
1abd0 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20 69 6e R .** without in
1abe0 73 65 72 74 69 6e 67 20 61 20 72 6f 77 20 69 6e serting a row in
1abf0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e to the database.
1ac00 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 .*/.void sqlite3
1ac10 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 _set_last_insert
1ac20 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 2c _rowid(sqlite3*,
1ac30 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
1ac40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1ac50 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 Count The Numbe
1ac60 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 r Of Rows Modifi
1ac70 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ed.** METHOD: sq
1ac80 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 lite3.**.** ^Thi
1ac90 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
1aca0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
1acb0 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 rows modified,
1acc0 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 inserted or.** d
1acd0 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f eleted by the mo
1ace0 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 st recently comp
1acf0 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 leted INSERT, UP
1ad00 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a DATE or DELETE.*
1ad10 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 * statement on t
1ad20 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1ad30 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 ection specified
1ad40 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 by the only par
1ad50 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 ameter..** ^Exec
1ad60 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 uting any other
1ad70 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 type of SQL stat
1ad80 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d ement does not m
1ad90 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a odify the value.
1ada0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 ** returned by t
1adb0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a his function..**
1adc0 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 .** ^Only change
1add0 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 s made directly
1ade0 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 by the INSERT, U
1adf0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 PDATE or DELETE
1ae00 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a statement are.**
1ae10 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 considered - au
1ae20 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 xiliary changes
1ae30 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 caused by [CREAT
1ae40 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 E TRIGGER | trig
1ae50 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 gers], .** [fore
1ae60 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d ign key actions]
1ae70 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f or [REPLACE] co
1ae80 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 nstraint resolut
1ae90 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e ion are not coun
1aea0 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e ted..** .** Chan
1aeb0 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 ges to a view th
1aec0 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 at are intercept
1aed0 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 ed by .** [INSTE
1aee0 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 AD OF trigger |
1aef0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 INSTEAD OF trigg
1af00 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 ers] are not cou
1af10 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 nted. ^The value
1af20 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 .** returned by
1af30 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
1af40 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 () immediately a
1af50 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 fter an INSERT,
1af60 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 UPDATE or .** DE
1af70 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 LETE statement r
1af80 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 un on a view is
1af90 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c always zero. Onl
1afa0 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 y changes made t
1afb0 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 o real .** table
1afc0 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a s are counted..*
1afd0 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 *.** Things are
1afe0 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 more complicated
1aff0 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f if the sqlite3_
1b000 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 changes() functi
1b010 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 on is.** execute
1b020 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 d while a trigge
1b030 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e r program is run
1b040 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 ning. This may h
1b050 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 appen if the.**
1b060 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 program uses the
1b070 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 [changes() SQL
1b080 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 function], or if
1b090 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c some other call
1b0a0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e back.** function
1b0b0 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 invokes sqlite3
1b0c0 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 _changes() direc
1b0d0 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 tly. Essentially
1b0e0 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a :.** .** <ul>.**
1b0f0 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 <li> ^(Before
1b100 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 entering a trig
1b110 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 ger program the
1b120 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
1b130 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 y.** sqli
1b140 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 te3_changes() fu
1b150 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e nction is saved.
1b160 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67 After the trigg
1b170 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 er program .**
1b180 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 has finish
1b190 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c ed, the original
1b1a0 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 value is restor
1b1b0 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c ed.)^.** .** <
1b1c0 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 li> ^(Within a t
1b1d0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 rigger program e
1b1e0 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 ach INSERT, UPDA
1b1f0 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a TE and DELETE .*
1b200 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 * stateme
1b210 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 nt sets the valu
1b220 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 e returned by sq
1b230 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 lite3_changes()
1b240 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 .** upon
1b250 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f completion as no
1b260 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c rmal. Of course,
1b270 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c this value will
1b280 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a not include .**
1b290 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e any chan
1b2a0 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 ges performed by
1b2b0 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 sub-triggers, a
1b2c0 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 s the sqlite3_ch
1b2d0 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 anges() .**
1b2e0 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 value will be
1b2f0 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f saved and resto
1b300 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73 red after each s
1b310 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 ub-trigger has r
1b320 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a un.)^.** </ul>.*
1b330 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e * .** ^This mean
1b340 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68 s that if the ch
1b350 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 anges() SQL func
1b360 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 tion (or similar
1b370 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 ) is used.** by
1b380 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 the first INSERT
1b390 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 , UPDATE or DELE
1b3a0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 TE statement wit
1b3b0 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 hin a trigger, i
1b3c0 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 t .** returns th
1b3d0 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 e value as set w
1b3e0 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 hen the calling
1b3f0 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 statement began
1b400 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 executing..** ^I
1b410 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20 f it is used by
1b420 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 the second or su
1b430 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 bsequent such st
1b440 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 atement within a
1b450 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f trigger .** pro
1b460 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 gram, the value
1b470 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 returned reflect
1b480 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
1b490 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 rows modified by
1b4a0 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 the .** previou
1b4b0 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 s INSERT, UPDATE
1b4c0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 or DELETE state
1b4d0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 ment within the
1b4e0 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a same trigger..**
1b4f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 .** See also the
1b500 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f [sqlite3_total_
1b510 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 changes()] inter
1b520 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f face, the.** [co
1b530 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 unt_changes prag
1b540 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 ma], and the [ch
1b550 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 anges() SQL func
1b560 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 tion]..**.** If
1b570 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
1b580 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 d makes changes
1b590 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 on the same data
1b5a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
1b5b0 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 ** while [sqlite
1b5c0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 3_changes()] is
1b5d0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 running then the
1b5e0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a value returned.
1b5f0 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 ** is unpredicta
1b600 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e ble and not mean
1b610 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 ingful..*/.int s
1b620 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 qlite3_changes(s
1b630 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
1b640 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c CAPI3REF: Total
1b650 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 Number Of Rows
1b660 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 Modified.** METH
1b670 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
1b680 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
1b690 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 returns the tot
1b6a0 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 al number of row
1b6b0 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 s inserted, modi
1b6c0 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 fied or.** delet
1b6d0 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 ed by all [INSER
1b6e0 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 T], [UPDATE] or
1b6f0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 [DELETE] stateme
1b700 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a nts completed.**
1b710 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 since the datab
1b720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 ase connection w
1b730 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 as opened, inclu
1b740 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 ding those execu
1b750 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f ted as.** part o
1b760 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 f trigger progra
1b770 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 ms. ^Executing a
1b780 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 ny other type of
1b790 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a SQL statement.*
1b7a0 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 * does not affec
1b7b0 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 t the value retu
1b7c0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
1b7d0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e total_changes().
1b7e0 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 .** .** ^Changes
1b7f0 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 made as part of
1b800 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 [foreign key ac
1b810 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 tions] are inclu
1b820 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f ded in the.** co
1b830 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d unt, but those m
1b840 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 ade as part of R
1b850 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e EPLACE constrain
1b860 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 t resolution are
1b870 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 .** not. ^Change
1b880 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 s to a view that
1b890 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 are intercepted
1b8a0 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 by INSTEAD OF t
1b8b0 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 riggers .** are
1b8c0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 not counted..**
1b8d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 .** See also the
1b8e0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 [sqlite3_change
1b8f0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 s()] interface,
1b900 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 the.** [count_ch
1b910 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 anges pragma], a
1b920 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 nd the [total_ch
1b930 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 anges() SQL func
1b940 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 tion]..**.** If
1b950 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
1b960 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 d makes changes
1b970 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 on the same data
1b980 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
1b990 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 ** while [sqlite
1b9a0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
1b9b0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 )] is running th
1b9c0 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 en the value.**
1b9d0 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 returned is unpr
1b9e0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f edictable and no
1b9f0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f t meaningful..*/
1ba00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 .int sqlite3_tot
1ba10 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 al_changes(sqlit
1ba20 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
1ba30 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 I3REF: Interrupt
1ba40 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 A Long-Running
1ba50 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a Query.** METHOD:
1ba60 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
1ba70 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 This function ca
1ba80 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 uses any pending
1ba90 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 database operat
1baa0 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 ion to abort and
1bab0 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 .** return at it
1bac0 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 s earliest oppor
1bad0 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 tunity. This rou
1bae0 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c tine is typicall
1baf0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 y.** called in r
1bb00 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 esponse to a use
1bb10 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 r action such as
1bb20 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 pressing "Cance
1bb30 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 l".** or Ctrl-C
1bb40 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 where the user w
1bb50 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 ants a long quer
1bb60 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 y operation to h
1bb70 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 alt.** immediate
1bb80 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 ly..**.** ^It is
1bb90 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 safe to call th
1bba0 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 is routine from
1bbb0 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 a thread differe
1bbc0 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 nt from the.** t
1bbd0 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 hread that is cu
1bbe0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 rrently running
1bbf0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 the database ope
1bc00 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a ration. But it.
1bc10 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 ** is not safe t
1bc20 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 o call this rout
1bc30 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 ine with a [data
1bc40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1bc50 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 that.** is clos
1bc60 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 ed or might clos
1bc70 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 e before sqlite3
1bc80 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 _interrupt() ret
1bc90 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 urns..**.** ^If
1bca0 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e an SQL operation
1bcb0 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 is very nearly
1bcc0 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 finished at the
1bcd0 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c time when.** sql
1bce0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
1bcf0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e is called, then
1bd00 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 it might not ha
1bd10 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 ve an opportunit
1bd20 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 y.** to be inter
1bd30 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 rupted and might
1bd40 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d continue to com
1bd50 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e pletion..**.** ^
1bd60 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e An SQL operation
1bd70 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 that is interru
1bd80 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e pted will return
1bd90 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 [SQLITE_INTERRU
1bda0 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 PT]..** ^If the
1bdb0 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 interrupted SQL
1bdc0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 operation is an
1bdd0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
1bde0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 or DELETE.** tha
1bdf0 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 t is inside an e
1be00 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
1be10 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e ion, then the en
1be20 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e tire transaction
1be30 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c .** will be roll
1be40 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 ed back automati
1be50 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 cally..**.** ^Th
1be60 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
1be70 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 upt(D) call is i
1be80 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 n effect until a
1be90 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e ll currently run
1bea0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 ning.** SQL stat
1beb0 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 ements on [datab
1bec0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1bed0 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e D complete. ^An
1bee0 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d y new SQL statem
1bef0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ents.** that are
1bf00 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 started after t
1bf10 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
1bf20 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 rupt() call and
1bf30 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 before the .** r
1bf40 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 unning statement
1bf50 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 s reaches zero a
1bf60 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 re interrupted a
1bf70 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 s if they had be
1bf80 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 en.** running pr
1bf90 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ior to the sqlit
1bfa0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 e3_interrupt() c
1bfb0 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 all. ^New SQL s
1bfc0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 tatements.** tha
1bfd0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 t are started af
1bfe0 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 ter the running
1bff0 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 statement count
1c000 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 reaches zero are
1c010 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 .** not effected
1c020 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f by the sqlite3_
1c030 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 interrupt()..**
1c040 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ^A call to sqlit
1c050 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 e3_interrupt(D)
1c060 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e that occurs when
1c070 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 there are no ru
1c080 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 nning.** SQL sta
1c090 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d tements is a no-
1c0a0 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 op and has no ef
1c0b0 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 fect on SQL stat
1c0c0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 ements.** that a
1c0d0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 re started after
1c0e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 the sqlite3_int
1c0f0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 errupt() call re
1c100 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 turns..*/.void s
1c110 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1c120 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
1c130 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 ** CAPI3REF: Det
1c140 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c ermine If An SQL
1c150 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f Statement Is Co
1c160 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 mplete.**.** The
1c170 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
1c180 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f useful during co
1c190 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 mmand-line input
1c1a0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 to determine if
1c1b0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c the.** currentl
1c1c0 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 y entered text s
1c1d0 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 eems to form a c
1c1e0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 omplete SQL stat
1c1f0 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 ement or.** if a
1c200 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 dditional input
1c210 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 is needed before
1c220 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 sending the tex
1c230 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 t into.** SQLite
1c240 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e for parsing. ^
1c250 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
1c260 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 eturn 1 if the i
1c270 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 nput string.** a
1c280 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 ppears to be a c
1c290 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 omplete SQL stat
1c2a0 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 ement. ^A state
1c2b0 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 ment is judged t
1c2c0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 o be.** complete
1c2d0 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 if it ends with
1c2e0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b a semicolon tok
1c2f0 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 en and is not a
1c300 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 prefix of a.** w
1c310 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 ell-formed CREAT
1c320 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d E TRIGGER statem
1c330 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e ent. ^Semicolon
1c340 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 s that are embed
1c350 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 ded within.** st
1c360 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 ring literals or
1c370 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 quoted identifi
1c380 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d er names or comm
1c390 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 ents are not.**
1c3a0 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 independent toke
1c3b0 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 ns (they are par
1c3c0 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 t of the token i
1c3d0 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 n which they are
1c3e0 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e .** embedded) an
1c3f0 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f d thus do not co
1c400 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 unt as a stateme
1c410 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 nt terminator.
1c420 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 ^Whitespace.** a
1c430 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 nd comments that
1c440 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 follow the fina
1c450 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 l semicolon are
1c460 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e ignored..**.** ^
1c470 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
1c480 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 eturn 0 if the s
1c490 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f tatement is inco
1c4a0 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a mplete. ^If a.*
1c4b0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
1c4c0 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 ion fails, then
1c4d0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 SQLITE_NOMEM is
1c4e0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
1c4f0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
1c500 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 do not parse the
1c510 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
1c520 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 thus.** will not
1c530 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 detect syntacti
1c540 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 cally incorrect
1c550 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 SQL..**.** ^(If
1c560 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 SQLite has not b
1c570 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 een initialized
1c580 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 using [sqlite3_i
1c590 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 nitialize()] pri
1c5a0 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 or .** to invoki
1c5b0 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c ng sqlite3_compl
1c5c0 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c ete16() then sql
1c5d0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
1c5e0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 ) is invoked.**
1c5f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 automatically by
1c600 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
1c610 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 e16(). If that
1c620 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 initialization f
1c630 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 ails,.** then th
1c640 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
1c650 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 rom sqlite3_comp
1c660 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 lete16() will be
1c670 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 non-zero.** reg
1c680 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
1c690 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e er or not the in
1c6a0 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c put SQL is compl
1c6b0 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 ete.)^.**.** The
1c6c0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 input to [sqlit
1c6d0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d e3_complete()] m
1c6e0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 ust be a zero-te
1c6f0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d rminated.** UTF-
1c700 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 8 string..**.**
1c710 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 The input to [sq
1c720 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
1c730 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 ()] must be a ze
1c740 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
1c750 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 UTF-16 string i
1c760 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 n native byte or
1c770 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 der..*/.int sqli
1c780 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e te3_complete(con
1c790 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 st char *sql);.i
1c7a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c nt sqlite3_compl
1c7b0 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 ete16(const void
1c7c0 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 *sql);../*.** C
1c7d0 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 API3REF: Registe
1c7e0 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 r A Callback To
1c7f0 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 Handle SQLITE_BU
1c800 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 SY Errors.** KEY
1c810 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e WORDS: {busy-han
1c820 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b dler callback} {
1c830 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a busy handler}.**
1c840 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
1c850 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1c860 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
1c870 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 (D,X,P) routine
1c880 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 sets a callback
1c890 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 function X.** th
1c8a0 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f at might be invo
1c8b0 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e ked with argumen
1c8c0 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 t P whenever.**
1c8d0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 an attempt is ma
1c8e0 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 de to access a d
1c8f0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 atabase table as
1c900 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a sociated with.**
1c910 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1c920 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e ction] D when an
1c930 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 other thread.**
1c940 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 or process has t
1c950 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e he table locked.
1c960 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
1c970 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 busy_handler() i
1c980 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
1c990 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a to implement.**
1c9a0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 [sqlite3_busy_t
1c9b0 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 imeout()] and [P
1c9c0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f RAGMA busy_timeo
1c9d0 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ut]..**.** ^If t
1c9e0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
1c9f0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b is NULL, then [
1ca00 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 SQLITE_BUSY].**
1ca10 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 is returned imme
1ca20 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 diately upon enc
1ca30 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f ountering the lo
1ca40 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 ck. ^If the bus
1ca50 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 y callback.** is
1ca60 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 not NULL, then
1ca70 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 the callback mig
1ca80 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 ht be invoked wi
1ca90 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 th two arguments
1caa0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
1cab0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
1cac0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
1cad0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
1cae0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 void* pointer w
1caf0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 hich.** is the t
1cb00 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f hird argument to
1cb10 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 sqlite3_busy_ha
1cb20 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 ndler(). ^The s
1cb30 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
1cb40 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 o.** the busy ha
1cb50 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 ndler callback i
1cb60 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
1cb70 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 times that the b
1cb80 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a usy handler has.
1cb90 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 ** been invoked
1cba0 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 previously for t
1cbb0 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 he same locking
1cbc0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a event. ^If the.
1cbd0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b ** busy callback
1cbe0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e returns 0, then
1cbf0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 no additional a
1cc00 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 ttempts are made
1cc10 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 to.** access th
1cc20 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b e database and [
1cc30 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 SQLITE_BUSY] is
1cc40 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 returned.** to t
1cc50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a he application..
1cc60 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 ** ^If the callb
1cc70 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ack returns non-
1cc80 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 zero, then anoth
1cc90 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 er attempt.** is
1cca0 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 made to access
1ccb0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 the database and
1ccc0 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 the cycle repea
1ccd0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 ts..**.** The pr
1cce0 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 esence of a busy
1ccf0 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f handler does no
1cd00 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 t guarantee that
1cd10 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f it will be invo
1cd20 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 ked.** when ther
1cd30 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e e is lock conten
1cd40 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 tion. ^If SQLite
1cd50 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 determines that
1cd60 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 invoking the bu
1cd70 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f sy.** handler co
1cd80 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 uld result in a
1cd90 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c deadlock, it wil
1cda0 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 l go ahead and r
1cdb0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 eturn [SQLITE_BU
1cdc0 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 SY].** to the ap
1cdd0 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 plication instea
1cde0 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 d of invoking th
1cdf0 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c e .** busy handl
1ce00 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 er..** Consider
1ce10 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 a scenario where
1ce20 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 one process is
1ce30 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c holding a read l
1ce40 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 ock that.** it i
1ce50 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d s trying to prom
1ce60 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 ote to a reserve
1ce70 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 d lock and.** a
1ce80 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 second process i
1ce90 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 s holding a rese
1cea0 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 rved lock that i
1ceb0 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 t is trying.** t
1cec0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 o promote to an
1ced0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 exclusive lock.
1cee0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 The first proce
1cef0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 ss cannot procee
1cf00 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 d.** because it
1cf10 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 is blocked by th
1cf20 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 e second and the
1cf30 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
1cf40 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 cannot.** procee
1cf50 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 d because it is
1cf60 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 blocked by the f
1cf70 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 irst. If both p
1cf80 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f rocesses.** invo
1cf90 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ke the busy hand
1cfa0 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 lers, neither wi
1cfb0 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 ll make any prog
1cfc0 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 ress. Therefore
1cfd0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 ,.** SQLite retu
1cfe0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 rns [SQLITE_BUSY
1cff0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 ] for the first
1d000 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 process, hoping
1d010 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c that this.** wil
1d020 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 l induce the fir
1d030 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 st process to re
1d040 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c lease its read l
1d050 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a ock and allow.**
1d060 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 the second proc
1d070 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a ess to proceed..
1d080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 **.** ^The defau
1d090 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b lt busy callback
1d0a0 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 is NULL..**.**
1d0b0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 ^(There can only
1d0c0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 be a single bus
1d0d0 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 y handler define
1d0e0 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 d for each.** [d
1d0f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1d100 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 on]. Setting a
1d110 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 new busy handler
1d120 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 clears any.** p
1d130 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 reviously set ha
1d140 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 ndler.)^ ^Note
1d150 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 that calling [sq
1d160 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
1d170 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c ut()].** or eval
1d180 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 uating [PRAGMA b
1d190 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 usy_timeout=N] w
1d1a0 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a ill change the.*
1d1b0 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 * busy handler a
1d1c0 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e nd thus clear an
1d1d0 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 y previously set
1d1e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
1d1f0 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 *.** The busy ca
1d200 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f llback should no
1d210 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f t take any actio
1d220 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 ns which modify
1d230 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
1d240 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
1d250 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 invoked the busy
1d260 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 handler. In ot
1d270 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 her words,.** th
1d280 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 e busy handler i
1d290 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e s not reentrant.
1d2a0 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f Any such actio
1d2b0 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 ns.** result in
1d2c0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 undefined behavi
1d2d0 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 or..** .** A bus
1d2e0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e y handler must n
1d2f0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 ot close the dat
1d300 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1d310 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 .** or [prepared
1d320 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
1d330 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 invoked the bus
1d340 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e y handler..*/.in
1d350 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 t sqlite3_busy_h
1d360 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c andler(sqlite3*,
1d370 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 int(*)(void*,int
1d380 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a ),void*);../*.**
1d390 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 CAPI3REF: Set A
1d3a0 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a Busy Timeout.**
1d3b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
1d3c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 .**.** ^This rou
1d3d0 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c tine sets a [sql
1d3e0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
1d3f0 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 r | busy handler
1d400 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a ] that sleeps.**
1d410 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 for a specified
1d420 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 amount of time
1d430 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 when a table is
1d440 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 locked. ^The ha
1d450 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c ndler.** will sl
1d460 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d eep multiple tim
1d470 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 es until at leas
1d480 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f t "ms" milliseco
1d490 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a nds of sleeping.
1d4a0 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 ** have accumula
1d4b0 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 ted. ^After at
1d4c0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 least "ms" milli
1d4d0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
1d4e0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 ing,.** the hand
1d4f0 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 ler returns 0 wh
1d500 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 ich causes [sqli
1d510 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 te3_step()] to r
1d520 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 eturn.** [SQLITE
1d530 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 _BUSY]..**.** ^C
1d540 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 alling this rout
1d550 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 ine with an argu
1d560 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f ment less than o
1d570 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a r equal to zero.
1d580 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c ** turns off all
1d590 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a busy handlers..
1d5a0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 **.** ^(There ca
1d5b0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 n only be a sing
1d5c0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 le busy handler
1d5d0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 for a particular
1d5e0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
1d5f0 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 nnection] at any
1d600 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 given moment.
1d610 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 If another busy
1d620 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 handler.** was d
1d630 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b efined (using [
1d640 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
1d650 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 dler()]) prior t
1d660 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 o calling.** thi
1d670 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 s routine, that
1d680 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c other busy handl
1d690 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e er is cleared.)^
1d6a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
1d6b0 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 [PRAGMA busy_t
1d6c0 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 imeout].*/.int s
1d6d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 qlite3_busy_time
1d6e0 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e out(sqlite3*, in
1d6f0 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 t ms);../*.** CA
1d700 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 PI3REF: Convenie
1d710 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 nce Routines For
1d720 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 Running Queries
1d730 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
1d740 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 te3.**.** This i
1d750 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 s a legacy inter
1d760 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 face that is pre
1d770 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 served for backw
1d780 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
1d790 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 ty..** Use of th
1d7a0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 is interface is
1d7b0 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e not recommended.
1d7c0 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f .**.** Definitio
1d7d0 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 n: A <b>result t
1d7e0 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f able</b> is memo
1d7f0 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 ry data structur
1d800 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 e created by the
1d810 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 .** [sqlite3_get
1d820 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 _table()] interf
1d830 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 ace. A result t
1d840 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 able records the
1d850 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 .** complete que
1d860 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 ry results from
1d870 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 one or more quer
1d880 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ies..**.** The t
1d890 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c able conceptuall
1d8a0 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f y has a number o
1d8b0 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d f rows and colum
1d8c0 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 ns. But.** thes
1d8d0 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f e numbers are no
1d8e0 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 t part of the re
1d8f0 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c sult table itsel
1d900 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d f. These.** num
1d910 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 bers are obtaine
1d920 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c d separately. L
1d930 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 et N be the numb
1d940 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e er of rows.** an
1d950 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 d M be the numbe
1d960 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a r of columns..**
1d970 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 .** A result tab
1d980 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f le is an array o
1d990 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 f pointers to ze
1d9a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
1d9b0 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 F-8 strings..**
1d9c0 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a There are (N+1)*
1d9d0 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 M elements in th
1d9e0 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 e array. The fi
1d9f0 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 rst M pointers p
1da00 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d oint.** to zero-
1da10 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e terminated strin
1da20 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e gs that contain
1da30 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 the names of th
1da40 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 e columns..** Th
1da50 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 e remaining entr
1da60 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f ies all point to
1da70 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 query results.
1da80 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 NULL values res
1da90 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 ult.** in NULL p
1daa0 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 ointers. All ot
1dab0 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 her values are i
1dac0 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 n their UTF-8 ze
1dad0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
1dae0 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e string represen
1daf0 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e tation as return
1db00 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
1db10 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a olumn_text()]..*
1db20 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 *.** A result ta
1db30 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 ble might consis
1db40 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 t of one or more
1db50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1db60 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f ons..** It is no
1db70 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 t safe to pass a
1db80 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 result table di
1db90 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 rectly to [sqlit
1dba0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 e3_free()]..** A
1dbb0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 result table sh
1dbc0 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 ould be dealloca
1dbd0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
1dbe0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d e3_free_table()]
1dbf0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 ..**.** ^(As an
1dc00 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 example of the r
1dc10 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d esult table form
1dc20 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 at, suppose a qu
1dc30 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 ery result.** is
1dc40 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
1dc50 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1dc60 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e pre>.** N
1dc70 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 ame | Age
1dc80 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d .** -----
1dc90 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1dca0 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 --.** Ali
1dcb0 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a ce | 43.**
1dcc0 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 Bob
1dcd0 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 | 28.**
1dce0 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c Cindy |
1dcf0 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 21.** </pre></b
1dd00 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
1dd10 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 There are two c
1dd20 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 olumn (M==2) and
1dd30 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d three rows (N==
1dd40 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 3). Thus the.**
1dd50 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 result table ha
1dd60 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 s 8 entries. Su
1dd70 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 ppose the result
1dd80 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 table is stored
1dd90 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 .** in an array
1dda0 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 names azResult.
1ddb0 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 Then azResult h
1ddc0 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e olds this conten
1ddd0 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 t:.**.** <blockq
1dde0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 uote><pre>.**
1ddf0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1de00 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 1;0] = "Name";.*
1de10 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1de20 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 t[1] = "Age"
1de30 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
1de40 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 sult[2] = "A
1de50 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 lice";.**
1de60 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d azResult[3]
1de70 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 = "43";.**
1de80 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1de90 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 4] = "Bob";.**
1dea0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
1deb0 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 91;5] = "28";.**
1dec0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1ded0 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 [6] = "Cindy
1dee0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1def0 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 esult[7] = "
1df00 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 21";.** </pre></
1df10 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
1df20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1df30 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e _get_table() fun
1df40 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 ction evaluates
1df50 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 one or more.** s
1df60 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 emicolon-separat
1df70 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ed SQL statement
1df80 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 s in the zero-te
1df90 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a rminated UTF-8.*
1dfa0 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 * string of its
1dfb0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 2nd parameter an
1dfc0 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 d returns a resu
1dfd0 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a lt table to the.
1dfe0 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e ** pointer given
1dff0 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 in its 3rd para
1e000 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 meter..**.** Aft
1e010 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 er the applicati
1e020 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 on has finished
1e030 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 with the result
1e040 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 from sqlite3_get
1e050 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 _table(),.** it
1e060 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 must pass the re
1e070 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 sult table point
1e080 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 er to sqlite3_fr
1e090 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 ee_table() in or
1e0a0 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 der to.** releas
1e0b0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 e the memory tha
1e0c0 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 t was malloced.
1e0d0 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 Because of the
1e0e0 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 way the.** [sqli
1e0f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 te3_malloc()] ha
1e100 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c ppens within sql
1e110 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
1e120 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a , the calling.**
1e130 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e function must n
1e140 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b ot try to call [
1e150 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
1e160 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a directly. Only.
1e170 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
1e180 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c _table()] is abl
1e190 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 e to release the
1e1a0 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 memory properly
1e1b0 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a and safely..**.
1e1c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 ** The sqlite3_g
1e1d0 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 et_table() inter
1e1e0 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e face is implemen
1e1f0 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 ted as a wrapper
1e200 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 around.** [sqli
1e210 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 te3_exec()]. Th
1e220 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 e sqlite3_get_ta
1e230 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f ble() routine do
1e240 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 es not have acce
1e250 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 ss.** to any int
1e260 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 ernal data struc
1e270 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e tures of SQLite.
1e280 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 It uses only t
1e290 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 he public.** int
1e2a0 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 erface defined h
1e2b0 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 ere. As a conse
1e2c0 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 quence, errors t
1e2d0 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 hat occur in the
1e2e0 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 .** wrapper laye
1e2f0 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 r outside of the
1e300 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 internal [sqlit
1e310 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 e3_exec()] call
1e320 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 are not.** refle
1e330 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 cted in subseque
1e340 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c nt calls to [sql
1e350 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 ite3_errcode()]
1e360 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 or.** [sqlite3_e
1e370 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 rrmsg()]..*/.int
1e380 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
1e390 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 le(. sqlite3 *d
1e3a0 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 b, /* A
1e3b0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 n open database
1e3c0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
1e3d0 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 *zSql, /* SQ
1e3e0 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 L to be evaluate
1e3f0 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 d */. char ***p
1e400 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 azResult, /*
1e410 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 Results of the q
1e420 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 uery */. int *p
1e430 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 nRow,
1e440 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 /* Number of res
1e450 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e ult rows written
1e460 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a here */. int *
1e470 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 pnColumn,
1e480 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 /* Number of re
1e490 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 sult columns wri
1e4a0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 tten here */. c
1e4b0 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 har **pzErrmsg
1e4c0 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 /* Error ms
1e4d0 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a g written here *
1e4e0 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 /.);.void sqlite
1e4f0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 3_free_table(cha
1e500 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a r **result);../*
1e510 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f .** CAPI3REF: Fo
1e520 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 rmatted String P
1e530 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e rinting Function
1e540 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f s.**.** These ro
1e550 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d utines are work-
1e560 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 alikes of the "p
1e570 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 rintf()" family
1e580 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 of functions.**
1e590 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 from the standar
1e5a0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 d C library..**
1e5b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 These routines u
1e5c0 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f nderstand most o
1e5d0 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 66 6f 72 f the common for
1e5e0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 matting options
1e5f0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e from.** the stan
1e600 64 61 72 64 20 6c 69 62 72 61 72 79 20 70 72 69 dard library pri
1e610 6e 74 66 28 29 20 0a 2a 2a 20 70 6c 75 73 20 73 ntf() .** plus s
1e620 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e ome additional n
1e630 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d on-standard form
1e640 61 74 73 20 28 5b 25 71 5d 2c 20 5b 25 51 5d 2c ats ([%q], [%Q],
1e650 20 5b 25 77 5d 2c 20 61 6e 64 20 5b 25 7a 5d 29 [%w], and [%z])
1e660 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 62 75 ..** See the [bu
1e670 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d ilt-in printf()]
1e680 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 documentation f
1e690 6f 72 20 64 65 74 61 69 6c 73 2e 0a 2a 2a 0a 2a or details..**.*
1e6a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d * ^The sqlite3_m
1e6b0 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c printf() and sql
1e6c0 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 ite3_vmprintf()
1e6d0 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 routines write t
1e6e0 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 heir.** results
1e6f0 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 into memory obta
1e700 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 ined from [sqlit
1e710 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 2e 0a e3_malloc64()]..
1e720 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 ** The strings r
1e730 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 eturned by these
1e740 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 two routines sh
1e750 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 ould be.** relea
1e760 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f sed by [sqlite3_
1e770 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 free()]. ^Both
1e780 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
1e790 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
1e7a0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 r if [sqlite3_ma
1e7b0 6c 6c 6f 63 36 34 28 29 5d 20 69 73 20 75 6e 61 lloc64()] is una
1e7c0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 ble to allocate
1e7d0 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 enough.** memory
1e7e0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 to hold the res
1e7f0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a ulting string..*
1e800 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 *.** ^(The sqlit
1e810 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f e3_snprintf() ro
1e820 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 utine is similar
1e830 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 to "snprintf()"
1e840 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 from.** the sta
1e850 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e ndard C library.
1e860 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 The result is
1e870 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 written into the
1e880 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c .** buffer suppl
1e890 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e ied as the secon
1e8a0 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 d parameter whos
1e8b0 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 e size is given
1e8c0 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 by.** the first
1e8d0 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 parameter. Note
1e8e0 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f that the order o
1e8f0 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 f the.** first t
1e900 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 wo parameters is
1e910 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 reversed from s
1e920 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 nprintf().)^ Th
1e930 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 is is an.** hist
1e940 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 orical accident
1e950 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 that cannot be f
1e960 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 ixed without bre
1e970 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 aking.** backwar
1e980 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
1e990 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 . ^(Note also t
1e9a0 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 hat sqlite3_snpr
1e9b0 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e intf().** return
1e9c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 s a pointer to i
1e9d0 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 ts buffer instea
1e9e0 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 d of the number
1e9f0 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 of.** characters
1ea00 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 actually writte
1ea10 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 n into the buffe
1ea20 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 r.)^ We admit t
1ea30 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 hat.** the numbe
1ea40 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 r of characters
1ea50 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 written would be
1ea60 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 a more useful r
1ea70 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 eturn.** value b
1ea80 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 ut we cannot cha
1ea90 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e nge the implemen
1eaa0 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 tation of sqlite
1eab0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
1eac0 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 now without brea
1ead0 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 king compatibili
1eae0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f ty..**.** ^As lo
1eaf0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 ng as the buffer
1eb00 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 size is greater
1eb10 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 than zero, sqli
1eb20 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
1eb30 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 * guarantees tha
1eb40 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 t the buffer is
1eb50 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d always zero-term
1eb60 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 inated. ^The fi
1eb70 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 rst.** parameter
1eb80 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 "n" is the tota
1eb90 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 l size of the bu
1eba0 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 ffer, including
1ebb0 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 space for.** the
1ebc0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
1ebd0 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 . So the longes
1ebe0 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 t string that ca
1ebf0 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a n be completely.
1ec00 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 ** written will
1ec10 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 be n-1 character
1ec20 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 s..**.** ^The sq
1ec30 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 lite3_vsnprintf(
1ec40 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 ) routine is a v
1ec50 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f arargs version o
1ec60 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e f sqlite3_snprin
1ec70 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 tf()..**.** See
1ec80 61 6c 73 6f 3a 20 20 5b 62 75 69 6c 74 2d 69 6e also: [built-in
1ec90 20 70 72 69 6e 74 66 28 29 5d 2c 20 5b 70 72 69 printf()], [pri
1eca0 6e 74 66 28 29 20 53 51 4c 20 66 75 6e 63 74 69 ntf() SQL functi
1ecb0 6f 6e 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c on].*/.char *sql
1ecc0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e ite3_mprintf(con
1ecd0 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 st char*,...);.c
1ece0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 har *sqlite3_vmp
1ecf0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 rintf(const char
1ed00 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 *, va_list);.cha
1ed10 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 r *sqlite3_snpri
1ed20 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f ntf(int,char*,co
1ed30 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b nst char*, ...);
1ed40 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 .char *sqlite3_v
1ed50 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 snprintf(int,cha
1ed60 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 r*,const char*,
1ed70 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a va_list);../*.**
1ed80 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 CAPI3REF: Memor
1ed90 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 y Allocation Sub
1eda0 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 system.**.** The
1edb0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 SQLite core use
1edc0 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f s these three ro
1edd0 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f utines for all o
1ede0 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 f its own.** int
1edf0 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c ernal memory all
1ee00 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 ocation needs. "
1ee10 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 Core" in the pre
1ee20 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a vious sentence.*
1ee30 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 * does not inclu
1ee40 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 de operating-sys
1ee50 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 tem specific VFS
1ee60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
1ee70 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 The.** Windows
1ee80 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 VFS uses native
1ee90 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 malloc() and fr
1eea0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 ee() for some op
1eeb0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 erations..**.**
1eec0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^The sqlite3_mal
1eed0 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 loc() routine re
1eee0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
1eef0 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 to a block.** of
1ef00 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 memory at least
1ef10 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 N bytes in leng
1ef20 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 th, where N is t
1ef30 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a he parameter..**
1ef40 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^If sqlite3_mal
1ef50 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 loc() is unable
1ef60 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 to obtain suffic
1ef70 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d ient free.** mem
1ef80 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 ory, it returns
1ef90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 a NULL pointer.
1efa0 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 ^If the paramet
1efb0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 er N to.** sqlit
1efc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a e3_malloc() is z
1efd0 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 ero or negative
1efe0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c then sqlite3_mal
1eff0 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a loc() returns.**
1f000 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
1f010 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1f020 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 te3_malloc64(N)
1f030 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 routine works ju
1f040 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 st like.** sqlit
1f050 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 e3_malloc(N) exc
1f060 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e ept that N is an
1f070 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 unsigned 64-bit
1f080 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 integer instead
1f090 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 .** of a signed
1f0a0 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 32-bit integer..
1f0b0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 **.** ^Calling s
1f0c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 qlite3_free() wi
1f0d0 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 th a pointer pre
1f0e0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 viously returned
1f0f0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d .** by sqlite3_m
1f100 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 alloc() or sqlit
1f110 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c e3_realloc() rel
1f120 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 eases that memor
1f130 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 y so.** that it
1f140 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e might be reused.
1f150 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 ^The sqlite3_f
1f160 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ree() routine is
1f170 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 .** a no-op if i
1f180 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 s called with a
1f190 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 NULL pointer. P
1f1a0 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f assing a NULL po
1f1b0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 inter.** to sqli
1f1c0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 te3_free() is ha
1f1d0 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 rmless. After b
1f1e0 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f eing freed, memo
1f1f0 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 ry.** should nei
1f200 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 ther be read nor
1f210 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 written. Even
1f220 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 reading previous
1f230 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f ly freed.** memo
1f240 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 ry might result
1f250 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f in a segmentatio
1f260 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 n fault or other
1f270 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a severe error..*
1f280 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 * Memory corrupt
1f290 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 ion, a segmentat
1f2a0 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 ion fault, or ot
1f2b0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 her severe error
1f2c0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 .** might result
1f2d0 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 if sqlite3_free
1f2e0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 () is called wit
1f2f0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 h a non-NULL poi
1f300 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 nter that.** was
1f310 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 not obtained fr
1f320 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f om sqlite3_mallo
1f330 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 c() or sqlite3_r
1f340 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 ealloc()..**.**
1f350 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 ^The sqlite3_rea
1f360 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 lloc(X,N) interf
1f370 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ace attempts to
1f380 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f resize a.** prio
1f390 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 r memory allocat
1f3a0 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c ion X to be at l
1f3b0 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a east N bytes..**
1f3c0 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d ^If the X param
1f3d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
1f3e0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 realloc(X,N).**
1f3f0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
1f400 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 r then its behav
1f410 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c ior is identical
1f420 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 to calling.** s
1f430 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 qlite3_malloc(N)
1f440 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 ..** ^If the N p
1f450 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
1f460 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
1f470 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e is zero or.** n
1f480 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 egative then the
1f490 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 behavior is exa
1f4a0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 ctly the same as
1f4b0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
1f4c0 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 te3_free(X)..**
1f4d0 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 ^sqlite3_realloc
1f4e0 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 (X,N) returns a
1f4f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d pointer to a mem
1f500 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
1f510 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 * of at least N
1f520 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 bytes in size or
1f530 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 NULL if insuffi
1f540 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 cient memory is
1f550 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 available..** ^I
1f560 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 f M is the size
1f570 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c of the prior all
1f580 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 ocation, then mi
1f590 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 n(N,M) bytes.**
1f5a0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c of the prior all
1f5b0 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 ocation are copi
1f5c0 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 ed into the begi
1f5d0 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 nning of buffer
1f5e0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 returned.** by s
1f5f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 qlite3_realloc(X
1f600 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f ,N) and the prio
1f610 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 r allocation is
1f620 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 freed..** ^If sq
1f630 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c lite3_realloc(X,
1f640 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 N) returns NULL
1f650 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 and N is positiv
1f660 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 e, then the.** p
1f670 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
1f680 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a is not freed..**
1f690 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1f6a0 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 _realloc64(X,N)
1f6b0 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 interfaces works
1f6c0 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 the same as.**
1f6d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1f6e0 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 X,N) except that
1f6f0 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 N is a 64-bit u
1f700 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 nsigned integer
1f710 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 instead.** of a
1f720 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 32-bit signed in
1f730 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 teger..**.** ^If
1f740 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 X is a memory a
1f750 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f llocation previo
1f760 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 usly obtained fr
1f770 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f om sqlite3_mallo
1f780 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f c(),.** sqlite3_
1f790 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 malloc64(), sqli
1f7a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f te3_realloc(), o
1f7b0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f r sqlite3_reallo
1f7c0 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 c64(), then.** s
1f7d0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 qlite3_msize(X)
1f7e0 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 returns the size
1f7f0 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 of that memory
1f800 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 allocation in by
1f810 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c tes..** ^The val
1f820 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ue returned by s
1f830 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 qlite3_msize(X)
1f840 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 might be larger
1f850 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a than the number.
1f860 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 ** of bytes requ
1f870 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 ested when X was
1f880 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 allocated. ^If
1f890 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 X is a NULL poi
1f8a0 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c nter then.** sql
1f8b0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 ite3_msize(X) re
1f8c0 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 turns zero. If
1f8d0 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 X points to some
1f8e0 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f thing that is no
1f8f0 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 t.** the beginni
1f900 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c ng of memory all
1f910 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 ocation, or if i
1f920 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f t points to a fo
1f930 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 rmerly.** valid
1f940 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1f950 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 n that has now b
1f960 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 een freed, then
1f970 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 the behavior.**
1f980 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 of sqlite3_msize
1f990 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 (X) is undefined
1f9a0 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 and possibly ha
1f9b0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rmful..**.** ^Th
1f9c0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 e memory returne
1f9d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c d by sqlite3_mal
1f9e0 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 loc(), sqlite3_r
1f9f0 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c ealloc(),.** sql
1fa00 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c ite3_malloc64(),
1fa10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 and sqlite3_rea
1fa20 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 lloc64().** is a
1fa30 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f lways aligned to
1fa40 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 at least an 8 b
1fa50 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 yte boundary, or
1fa60 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 to a.** 4 byte
1fa70 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 boundary if the
1fa80 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 [SQLITE_4_BYTE_A
1fa90 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 LIGNED_MALLOC] c
1faa0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f ompile-time.** o
1fab0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a ption is used..*
1fac0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 *.** In SQLite v
1fad0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 ersion 3.5.0 and
1fae0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 3.5.1, it was p
1faf0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e ossible to defin
1fb00 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f e.** the SQLITE_
1fb10 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f OMIT_MEMORY_ALLO
1fb20 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 CATION which wou
1fb30 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 ld cause the bui
1fb40 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 lt-in.** impleme
1fb50 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 ntation of these
1fb60 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
1fb70 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 omitted. That c
1fb80 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 apability.** is
1fb90 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 no longer provid
1fba0 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d ed. Only built-
1fbb0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
1fbc0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 tors can be used
1fbd0 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f ..**.** Prior to
1fbe0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
1fbf0 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 3.7.10, the Wind
1fc00 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 ows OS interface
1fc10 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a layer called.**
1fc20 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c the system mall
1fc30 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
1fc40 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f directly when co
1fc50 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 nverting.** file
1fc60 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 names between th
1fc70 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 e UTF-8 encoding
1fc80 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a used by SQLite.
1fc90 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 ** and whatever
1fca0 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e filename encodin
1fcb0 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 g is used by the
1fcc0 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 particular Wind
1fcd0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 ows.** installat
1fce0 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c ion. Memory all
1fcf0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 ocation errors w
1fd00 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 ere detected, bu
1fd10 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 t.** they were r
1fd20 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 eported back as
1fd30 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e [SQLITE_CANTOPEN
1fd40 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ] or.** [SQLITE_
1fd50 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 IOERR] rather th
1fd60 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d an [SQLITE_NOMEM
1fd70 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 ]..**.** The poi
1fd80 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 nter arguments t
1fd90 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
1fda0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
1fdb0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 realloc()].** mu
1fdc0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c st be either NUL
1fdd0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 L or else pointe
1fde0 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d rs obtained from
1fdf0 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f a prior.** invo
1fe00 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 cation of [sqlit
1fe10 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 e3_malloc()] or
1fe20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
1fe30 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a ()] that have.**
1fe40 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 not yet been re
1fe50 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 leased..**.** Th
1fe60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
1fe70 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 st not read or w
1fe80 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 rite any part of
1fe90 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d .** a block of m
1fea0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 emory after it h
1feb0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 as been released
1fec0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
1fed0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 e3_free()] or [s
1fee0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1fef0 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 ]..*/.void *sqli
1ff00 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b te3_malloc(int);
1ff10 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d .void *sqlite3_m
1ff20 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f alloc64(sqlite3_
1ff30 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 uint64);.void *s
1ff40 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 qlite3_realloc(v
1ff50 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 oid*, int);.void
1ff60 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f *sqlite3_reallo
1ff70 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 c64(void*, sqlit
1ff80 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 e3_uint64);.void
1ff90 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f sqlite3_free(vo
1ffa0 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 id*);.sqlite3_ui
1ffb0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 nt64 sqlite3_msi
1ffc0 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ze(void*);../*.*
1ffd0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f * CAPI3REF: Memo
1ffe0 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 ry Allocator Sta
1fff0 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 tistics.**.** SQ
20000 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 Lite provides th
20010 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 ese two interfac
20020 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 es for reporting
20030 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a on the status.*
20040 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
20050 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 3_malloc()], [sq
20060 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 lite3_free()], a
20070 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c nd [sqlite3_real
20080 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e loc()].** routin
20090 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 es, which form t
200a0 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f he built-in memo
200b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 ry allocation su
200c0 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e bsystem..**.** ^
200d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
200e0 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 ory_used()] rout
200f0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
20100 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a number of bytes.
20110 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 ** of memory cur
20120 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 rently outstandi
20130 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 ng (malloced but
20140 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 not freed)..**
20150 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 ^The [sqlite3_me
20160 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
20170 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ] routine return
20180 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a s the maximum.**
20190 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 value of [sqlit
201a0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
201b0 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 ] since the high
201c0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 -water mark.** w
201d0 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 as last reset.
201e0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 ^The values retu
201f0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
20200 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 _memory_used()]
20210 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
20220 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
20230 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 ()] include any
20240 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 overhead.** adde
20250 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 d by SQLite in i
20260 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ts implementatio
20270 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 n of [sqlite3_ma
20280 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 lloc()],.** but
20290 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 not overhead add
202a0 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e ed by the any un
202b0 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 derlying system
202c0 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 library.** routi
202d0 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 nes that [sqlite
202e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 3_malloc()] may
202f0 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 call..**.** ^The
20300 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 memory high-wat
20310 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 er mark is reset
20320 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 to the current
20330 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c value of.** [sql
20340 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
20350 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 ()] if and only
20360 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
20370 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
20380 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
20390 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 ()] is true. ^T
203a0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
203b0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 d.** by [sqlite3
203c0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
203d0 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 r(1)] is the hig
203e0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 h-water mark.**
203f0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 prior to the res
20400 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 et..*/.sqlite3_i
20410 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d nt64 sqlite3_mem
20420 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a ory_used(void);.
20430 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
20440 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
20450 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 hwater(int reset
20460 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Flag);../*.** CA
20470 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 PI3REF: Pseudo-R
20480 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e andom Number Gen
20490 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c erator.**.** SQL
204a0 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 ite contains a h
204b0 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 igh-quality pseu
204c0 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 do-random number
204d0 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 generator (PRNG
204e0 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c ) used to.** sel
204f0 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 ect random [ROWI
20500 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e D | ROWIDs] when
20510 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 inserting new r
20520 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 ecords into a ta
20530 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 ble that.** alre
20540 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 ady uses the lar
20550 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 gest possible [R
20560 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 OWID]. The PRNG
20570 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f is also used fo
20580 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 r.** the build-i
20590 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 n random() and r
205a0 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 andomblob() SQL
205b0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 functions. This
205c0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 interface allow
205d0 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e s.** application
205e0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 s to access the
205f0 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 same PRNG for ot
20600 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a her purposes..**
20610 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 .** ^A call to t
20620 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 his routine stor
20630 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 es N bytes of ra
20640 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 ndomness into bu
20650 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 ffer P..** ^The
20660 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 P parameter can
20670 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 be a NULL pointe
20680 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 r..**.** ^If thi
20690 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f s routine has no
206a0 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c t been previousl
206b0 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 y called or if t
206c0 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 he previous.** c
206d0 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 all had N less t
206e0 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c han one or a NUL
206f0 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c L pointer for P,
20700 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 then the PRNG i
20710 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e s.** seeded usin
20720 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 g randomness obt
20730 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 ained from the x
20740 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f Randomness metho
20750 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 d of.** the defa
20760 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
20770 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 ] object..** ^If
20780 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 the previous ca
20790 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 ll to this routi
207a0 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 ne had an N of 1
207b0 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a or more and a.*
207c0 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 * non-NULL P the
207d0 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e n the pseudo-ran
207e0 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 domness is gener
207f0 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c ated.** internal
20800 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 ly and without r
20810 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b ecourse to the [
20820 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 sqlite3_vfs] xRa
20830 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 ndomness.** meth
20840 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 od..*/.void sqli
20850 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 te3_randomness(i
20860 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a nt N, void *P);.
20870 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
20880 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 Compile-Time Au
20890 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c thorization Call
208a0 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a backs.** METHOD:
208b0 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 sqlite3.** KEYW
208c0 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 ORDS: {authorize
208d0 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a r callback}.**.*
208e0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 * ^This routine
208f0 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 registers an aut
20900 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
20910 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c with a particul
20920 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ar.** [database
20930 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 connection], sup
20940 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 plied in the fir
20950 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 st argument..**
20960 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 ^The authorizer
20970 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
20980 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 ked as SQL state
20990 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 ments are being
209a0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b compiled.** by [
209b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
209c0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e )] or its varian
209d0 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ts [sqlite3_prep
209e0 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 are_v2()],.** [s
209f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
20a00 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 3()], [sqlite3_p
20a10 72 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 repare16()], [sq
20a20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
20a30 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 v2()],.** and [s
20a40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
20a50 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 _v3()]. ^At var
20a60 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 ious.** points d
20a70 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c uring the compil
20a80 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 ation process, a
20a90 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 s logic is being
20aa0 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 created.** to p
20ab0 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 erform various a
20ac0 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 ctions, the auth
20ad0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
20ae0 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a is invoked to.**
20af0 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 see if those ac
20b00 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 tions are allowe
20b10 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 d. ^The authori
20b20 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f zer callback sho
20b30 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 uld.** return [S
20b40 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c QLITE_OK] to all
20b50 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b ow the action, [
20b60 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 SQLITE_IGNORE] t
20b70 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a o disallow the.*
20b80 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f * specific actio
20b90 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 n but allow the
20ba0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f SQL statement to
20bb0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a continue to be.
20bc0 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 ** compiled, or
20bd0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f [SQLITE_DENY] to
20be0 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 cause the entir
20bf0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
20c00 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 to be.** rejecte
20c10 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e d with an error.
20c20 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 ^If the author
20c30 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 izer callback re
20c40 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c turns.** any val
20c50 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 ue other than [S
20c60 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b QLITE_IGNORE], [
20c70 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b SQLITE_OK], or [
20c80 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 SQLITE_DENY].**
20c90 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 then the [sqlite
20ca0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
20cb0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 or equivalent ca
20cc0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 ll that triggere
20cd0 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 d.** the authori
20ce0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 zer will fail wi
20cf0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 th an error mess
20d00 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 age..**.** When
20d10 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
20d20 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
20d30 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 , that means the
20d40 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 operation.** re
20d50 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 quested is ok.
20d60 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 ^When the callba
20d70 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
20d80 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a TE_DENY], the.**
20d90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
20da0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 e_v2()] or equiv
20db0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 alent call that
20dc0 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a triggered the.**
20dd0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c authorizer will
20de0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 fail with an er
20df0 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c ror message expl
20e00 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 aining that.** a
20e10 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e ccess is denied.
20e20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 .**.** ^The fir
20e30 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
20e40 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
20e50 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 allback is a cop
20e60 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a y of the third.*
20e70 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 * parameter to t
20e80 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 he sqlite3_set_a
20e90 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 uthorizer() inte
20ea0 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f rface. ^The seco
20eb0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 nd parameter.**
20ec0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
20ed0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 is an integer [S
20ee0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 QLITE_COPY | act
20ef0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 ion code] that s
20f00 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 pecifies.** the
20f10 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f particular actio
20f20 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a n to be authoriz
20f30 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 ed. ^The third t
20f40 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 hrough sixth par
20f50 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 ameters.** to th
20f60 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 e callback are e
20f70 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 ither NULL point
20f80 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d ers or zero-term
20f90 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a 2a inated strings.*
20fa0 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 * that contain a
20fb0 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c dditional detail
20fc0 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 s about the acti
20fd0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 on to be authori
20fe0 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 zed..** Applicat
20ff0 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79 73 ions must always
21000 20 62 65 20 70 72 65 70 61 72 65 64 20 74 6f 20 be prepared to
21010 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c encounter a NULL
21020 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a pointer in any.
21030 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 ** of the third
21040 74 68 72 6f 75 67 68 20 74 68 65 20 73 69 78 74 through the sixt
21050 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 h parameters of
21060 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f the authorizatio
21070 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a n callback..**.*
21080 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e * ^If the action
21090 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 code is [SQLITE
210a0 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 _READ].** and th
210b0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
210c0 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 ns [SQLITE_IGNOR
210d0 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b E] then the.** [
210e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
210f0 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 nt] statement is
21100 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 constructed to
21110 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 substitute.** a
21120 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c NULL value in pl
21130 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 ace of the table
21140 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 column that wou
21150 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 ld have.** been
21160 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f read if [SQLITE_
21170 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 OK] had been ret
21180 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c urned. The [SQL
21190 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 ITE_IGNORE].** r
211a0 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 eturn can be use
211b0 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 d to deny an unt
211c0 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 rusted user acce
211d0 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c ss to individual
211e0 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 .** columns of a
211f0 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e table..** ^When
21200 20 61 20 74 61 62 6c 65 20 69 73 20 72 65 66 65 a table is refe
21210 72 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45 4c renced by a [SEL
21220 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 ECT] but no colu
21230 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a mn values are.**
21240 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20 extracted from
21250 74 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72 20 that table (for
21260 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 example in a que
21270 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 ry like.** "SELE
21280 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d CT count(*) FROM
21290 20 74 61 62 22 29 20 74 68 65 6e 20 74 68 65 20 tab") then the
212a0 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 [SQLITE_READ] au
212b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
212c0 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 k.** is invoked
212d0 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74 61 once for that ta
212e0 62 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75 6d ble with a colum
212f0 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 61 n name that is a
21300 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a n empty string..
21310 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f ** ^If the actio
21320 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 n code is [SQLIT
21330 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 E_DELETE] and th
21340 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
21350 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 ns.** [SQLITE_IG
21360 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b NORE] then the [
21370 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f DELETE] operatio
21380 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 n proceeds but t
21390 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 he.** [truncate
213a0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 optimization] is
213b0 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c disabled and al
213c0 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 l rows are delet
213d0 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e ed individually.
213e0 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 .**.** An author
213f0 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 izer is used whe
21400 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 n [sqlite3_prepa
21410 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a re | preparing].
21420 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
21430 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 s from an untrus
21440 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 ted source, to e
21450 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 nsure that the S
21460 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
21470 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 do not try to a
21480 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 ccess data they
21490 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 are not allowed
214a0 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 to see, or that
214b0 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 they do not.** t
214c0 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 ry to execute ma
214d0 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e licious statemen
214e0 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 ts that damage t
214f0 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f he database. Fo
21500 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e r.** example, an
21510 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 application may
21520 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f allow a user to
21530 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 enter arbitrary
21540 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 .** SQL queries
21550 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 for evaluation b
21560 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 y a database. B
21570 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ut the applicati
21580 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 on does.** not w
21590 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 ant the user to
215a0 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 be able to make
215b0 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 arbitrary change
215c0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 s to the.** data
215d0 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 base. An author
215e0 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 izer could then
215f0 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 be put in place
21600 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 while the.** use
21610 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 r-entered SQL is
21620 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f being [sqlite3_
21630 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 prepare | prepar
21640 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 ed] that.** disa
21650 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 llows everything
21660 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d except [SELECT]
21670 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a statements..**.
21680 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** Applications
21690 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f that need to pro
216a0 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e cess SQL from un
216b0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a trusted sources.
216c0 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f ** might also co
216d0 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 nsider lowering
216e0 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 resource limits
216f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c using [sqlite3_l
21700 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c imit()].** and l
21710 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 imiting database
21720 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 size using the
21730 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d [max_page_count]
21740 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 [PRAGMA].** in
21750 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e addition to usin
21760 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e g an authorizer.
21770 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 .**.** ^(Only a
21780 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 single authorize
21790 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 r can be in plac
217a0 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 e on a database
217b0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 connection.** at
217c0 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 a time. Each c
217d0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
217e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 et_authorizer ov
217f0 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 errides the.** p
21800 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 revious call.)^
21810 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 ^Disable the au
21820 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 thorizer by inst
21830 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 alling a NULL ca
21840 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 llback..** The a
21850 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 uthorizer is dis
21860 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
21870 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 ..**.** The auth
21880 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
21890 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 must not do anyt
218a0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d hing that will m
218b0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 odify.** the dat
218c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
218d0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
218e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
218f0 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 lback..** Note t
21900 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hat [sqlite3_pre
21910 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b pare_v2()] and [
21920 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
21930 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 both modify thei
21940 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f r.** database co
21950 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 nnections for th
21960 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f e meaning of "mo
21970 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 dify" in this pa
21980 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e ragraph..**.** ^
21990 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 When [sqlite3_pr
219a0 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 epare_v2()] is u
219b0 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 sed to prepare a
219c0 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a statement, the.
219d0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 ** statement mig
219e0 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 ht be re-prepare
219f0 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 d during [sqlite
21a00 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 3_step()] due to
21a10 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 a .** schema ch
21a20 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 ange. Hence, th
21a30 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
21a40 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 ould ensure that
21a50 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 the.** correct
21a60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
21a70 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 ack remains in p
21a80 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 lace during the
21a90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
21aa0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 ..**.** ^Note th
21ab0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 at the authorize
21ac0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
21ad0 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e voked only durin
21ae0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 g.** [sqlite3_pr
21af0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 epare()] or its
21b00 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f variants. Autho
21b10 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a rization is not.
21b20 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 ** performed dur
21b30 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 ing statement ev
21b40 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c aluation in [sql
21b50 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e ite3_step()], un
21b60 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 less.** as state
21b70 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 d in the previou
21b80 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c s paragraph, sql
21b90 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f ite3_step() invo
21ba0 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 kes.** sqlite3_p
21bb0 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 repare_v2() to r
21bc0 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 eprepare a state
21bd0 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 ment after a sch
21be0 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 ema change..*/.i
21bf0 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 nt sqlite3_set_a
21c00 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c uthorizer(. sql
21c10 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 ite3*,. int (*x
21c20 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c Auth)(void*,int,
21c30 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
21c40 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
21c50 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 ar*,const char*)
21c60 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 ,. void *pUserD
21c70 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ata.);../*.** CA
21c80 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a PI3REF: Authoriz
21c90 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a er Return Codes.
21ca0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 **.** The [sqlit
21cb0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
21cc0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 r | authorizer c
21cd0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
21ce0 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e ] must.** return
21cf0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f either [SQLITE_
21d00 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 OK] or one of th
21d10 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 ese two constant
21d20 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f s in order.** to
21d30 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 signal SQLite w
21d40 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
21d50 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d e action is perm
21d60 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a itted. See the.
21d70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f ** [sqlite3_set_
21d80 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 authorizer | aut
21d90 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 horizer document
21da0 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 ation] for addit
21db0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 ional.** informa
21dc0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 tion..**.** Note
21dd0 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e that SQLITE_IGN
21de0 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 ORE is also used
21df0 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 as a [conflict
21e00 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d resolution mode]
21e10 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f .** returned fro
21e20 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 m the [sqlite3_v
21e30 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 tab_on_conflict(
21e40 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f )] interface..*/
21e50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
21e60 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 DENY 1 /* Ab
21e70 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 ort the SQL stat
21e80 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 ement with an er
21e90 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ror */.#define S
21ea0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 QLITE_IGNORE 2
21eb0 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 /* Don't allow
21ec0 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 access, but don'
21ed0 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 t generate an er
21ee0 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 ror */../*.** CA
21ef0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a PI3REF: Authoriz
21f00 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a er Action Codes.
21f10 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 **.** The [sqlit
21f20 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
21f30 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 r()] interface r
21f40 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 egisters a callb
21f50 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ack function.**
21f60 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 that is invoked
21f70 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 to authorize cer
21f80 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 tain SQL stateme
21f90 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 nt actions. The
21fa0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
21fb0 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c eter to the call
21fc0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 back is an integ
21fd0 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 er code that spe
21fe0 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 cifies.** what a
21ff0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 ction is being a
22000 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 uthorized. Thes
22010 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 e are the intege
22020 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 r action codes t
22030 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f hat.** the autho
22040 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d rizer callback m
22050 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a ay be passed..**
22060 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e .** These action
22070 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 code values sig
22080 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f nify what kind o
22090 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 f operation is t
220a0 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a o be.** authoriz
220b0 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 ed. The 3rd and
220c0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 4th parameters
220d0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 to the authoriza
220e0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b tion.** callback
220f0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 function will b
22100 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 e parameters or
22110 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f NULL depending o
22120 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 n which of these
22130 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 .** codes is use
22140 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
22150 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 parameter. ^(Th
22160 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
22170 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 to the.** author
22180 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
22190 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
221a0 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e database ("main
221b0 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 ", "temp",.** et
221c0 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c c.) if applicabl
221d0 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 e.)^ ^The 6th p
221e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
221f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
22200 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 ack.** is the na
22210 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d me of the inner-
22220 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 most trigger or
22230 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 view that is res
22240 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 ponsible for.**
22250 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d the access attem
22260 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 pt or NULL if th
22270 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 is access attemp
22280 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 t is directly fr
22290 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 om.** top-level
222a0 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a SQL code..*/./**
222b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
222c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
222d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a ********* 3rd **
222e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a ********** 4th *
222f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 **********/.#def
22300 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
22310 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 E_INDEX
22320 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 1 /* Index Na
22330 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
22340 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
22350 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
22360 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
22370 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 2 /* Table Nam
22380 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
22390 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
223a0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
223b0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 TEMP_INDEX 3
223c0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
223d0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
223e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
223f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
22400 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 EMP_TABLE 4
22410 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
22420 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
22430 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22440 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
22450 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 MP_TRIGGER 5
22460 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
22470 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
22480 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
22490 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
224a0 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 P_VIEW 6
224b0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
224c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
224d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
224e0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 LITE_CREATE_TRIG
224f0 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f GER 7 /
22500 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
22510 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
22520 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22530 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 ITE_CREATE_VIEW
22540 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 8 /*
22550 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
22560 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
22570 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22580 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 TE_DELETE
22590 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 9 /*
225a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
225b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
225c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
225d0 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 E_DROP_INDEX
225e0 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 10 /* I
225f0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
22600 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
22610 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22620 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 _DROP_TABLE
22630 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 11 /* Ta
22640 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
22650 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
22660 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22670 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 DROP_TEMP_INDEX
22680 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 12 /* Ind
22690 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
226a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
226b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
226c0 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 ROP_TEMP_TABLE
226d0 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 13 /* Tabl
226e0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
226f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
22700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
22710 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 OP_TEMP_TRIGGER
22720 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 14 /* Trigg
22730 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
22740 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
22750 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
22760 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 P_TEMP_VIEW
22770 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 15 /* View N
22780 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
22790 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
227a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
227b0 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 _TRIGGER
227c0 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 16 /* Trigger
227d0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
227e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
227f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
22800 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 VIEW
22810 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 17 /* View Nam
22820 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
22830 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
22840 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 ne SQLITE_INSERT
22850 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
22860 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 8 /* Table Nam
22870 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
22880 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
22890 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 e SQLITE_PRAGMA
228a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 19
228b0 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d /* Pragma Nam
228c0 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 e 1st arg or
228d0 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 NULL */.#define
228e0 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 SQLITE_READ
228f0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20
22900 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
22910 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 Column Name
22920 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22930 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 SQLITE_SELECT
22940 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 21
22950 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 /* NULL
22960 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
22970 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
22980 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f QLITE_TRANSACTIO
22990 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 N 22
229a0 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 /* Operation
229b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
229c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
229d0 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 LITE_UPDATE
229e0 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 23 /
229f0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
22a00 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 Column Name
22a10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22a20 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 ITE_ATTACH
22a30 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 24 /*
22a40 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 Filename
22a50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
22a60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22a70 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 TE_DETACH
22a80 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 25 /*
22a90 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 Database Name
22aa0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
22ab0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
22ac0 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 E_ALTER_TABLE
22ad0 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 26 /* D
22ae0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 atabase Name T
22af0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
22b00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22b10 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 _REINDEX
22b20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 27 /* In
22b30 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 dex Name NU
22b40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
22b50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22b60 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 ANALYZE
22b70 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 28 /* Tab
22b80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
22b90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
22ba0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
22bb0 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 REATE_VTABLE
22bc0 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 29 /* Tabl
22bd0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 e Name Modu
22be0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 le Name */.#
22bf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
22c00 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 OP_VTABLE
22c10 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 30 /* Table
22c20 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c Name Modul
22c30 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 e Name */.#d
22c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e efine SQLITE_FUN
22c50 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 CTION
22c60 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 31 /* NULL
22c70 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 Functi
22c80 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 on Name */.#de
22c90 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 fine SQLITE_SAVE
22ca0 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 POINT
22cb0 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 32 /* Operati
22cc0 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 on Savepoi
22cd0 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 nt Name */.#def
22ce0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 ine SQLITE_COPY
22cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
22d00 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 0 /* No longe
22d10 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e r used */.#defin
22d20 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 e SQLITE_RECURSI
22d30 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 VE 33
22d40 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 /* NULL
22d50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
22d60 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 */../*.**
22d70 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e CAPI3REF: Tracin
22d80 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 g And Profiling
22d90 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 Functions.** MET
22da0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
22db0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
22dc0 73 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64 s are deprecated
22dd0 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 . Use the [sqlit
22de0 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 e3_trace_v2()] i
22df0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 nterface.** inst
22e00 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69 ead of the routi
22e10 6e 65 73 20 64 65 73 63 72 69 62 65 64 20 68 65 nes described he
22e20 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 re..**.** These
22e30 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 routines registe
22e40 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 r callback funct
22e50 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 ions that can be
22e60 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 used for.** tra
22e70 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 cing and profili
22e80 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e ng the execution
22e90 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e of SQL statemen
22ea0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 ts..**.** ^The c
22eb0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
22ec0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 registered by s
22ed0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 qlite3_trace() i
22ee0 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 s invoked at.**
22ef0 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 various times wh
22f00 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d en an SQL statem
22f10 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e ent is being run
22f20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 by [sqlite3_ste
22f30 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 p()]..** ^The sq
22f40 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 lite3_trace() ca
22f50 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
22f60 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 d with a UTF-8 r
22f70 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a endering of the.
22f80 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
22f90 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 text as the sta
22fa0 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 tement first beg
22fb0 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a ins executing..*
22fc0 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 * ^(Additional s
22fd0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 qlite3_trace() c
22fe0 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f allbacks might o
22ff0 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 ccur.** as each
23000 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f triggered subpro
23010 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e gram is entered.
23020 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 The callbacks
23030 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 for triggers.**
23040 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 contain a UTF-8
23050 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 SQL comment that
23060 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 identifies the
23070 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a trigger.)^.**.**
23080 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 The [SQLITE_TRA
23090 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 CE_SIZE_LIMIT] c
230a0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
230b0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 on can be used t
230c0 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c o limit.** the l
230d0 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 ength of [bound
230e0 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e parameter] expan
230f0 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 sion in the outp
23100 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 ut of sqlite3_tr
23110 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ace()..**.** ^Th
23120 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
23130 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
23140 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c y sqlite3_profil
23150 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a e() is invoked.*
23160 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 * as each SQL st
23170 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 atement finishes
23180 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 . ^The profile
23190 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e callback contain
231a0 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 s.** the origina
231b0 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 l statement text
231c0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 and an estimate
231d0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 of wall-clock t
231e0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f ime.** of how lo
231f0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e ng that statemen
23200 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 t took to run.
23210 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c ^The profile cal
23220 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 lback.** time is
23230 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e in units of nan
23240 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 oseconds, howeve
23250 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d r the current im
23260 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 plementation.**
23270 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 is only capable
23280 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 of millisecond r
23290 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 esolution so the
232a0 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 six least signi
232b0 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 ficant.** digits
232c0 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 in the time are
232d0 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 meaningless. F
232e0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
232f0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 f SQLite.** migh
23300 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 t provide greate
23310 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 r resolution on
23320 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c the profiler cal
23330 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 lback. The.** s
23340 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 qlite3_profile()
23350 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e function is con
23360 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 sidered experime
23370 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 ntal and is.** s
23380 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
23390 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 in future versi
233a0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ons of SQLite..*
233b0 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 /.SQLITE_DEPRECA
233c0 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 TED void *sqlite
233d0 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 3_trace(sqlite3*
233e0 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 ,. void(*xTrac
233f0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 e)(void*,const c
23400 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 har*), void*);.S
23410 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
23420 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 void *sqlite3_p
23430 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c rofile(sqlite3*,
23440 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 . void(*xProfi
23450 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 le)(void*,const
23460 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 char*,sqlite3_ui
23470 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a nt64), void*);..
23480 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
23490 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 SQL Trace Event
234a0 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 Codes.** KEYWORD
234b0 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a S: SQLITE_TRACE.
234c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
234d0 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 tants identify c
234e0 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 lasses of events
234f0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e that can be mon
23500 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 itored.** using
23510 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 the [sqlite3_tra
23520 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 ce_v2()] tracing
23530 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 4d 20 61 logic. The M a
23540 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 rgument.** to [s
23550 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 qlite3_trace_v2(
23560 44 2c 4d 2c 58 2c 50 29 5d 20 69 73 20 61 6e 20 D,M,X,P)] is an
23570 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f OR-ed combinatio
23580 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 n of one or more
23590 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f of.** the follo
235a0 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 wing constants.
235b0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 ^The first argu
235c0 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 ment to the trac
235d0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 e callback.** is
235e0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c one of the foll
235f0 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e owing constants.
23600 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 .**.** New traci
23610 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 ng constants may
23620 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
23630 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a ure releases..**
23640 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c .** ^A trace cal
23650 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61 lback has four a
23660 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 rguments: xCallb
23670 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a ack(T,C,P,X)..**
23680 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 ^The T argument
23690 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 is one of the i
236a0 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64 65 nteger type code
236b0 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 s above..** ^The
236c0 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 C argument is a
236d0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e copy of the con
236e0 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73 text pointer pas
236f0 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a sed in as the.**
23700 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
23710 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 to [sqlite3_tra
23720 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 ce_v2()]..** The
23730 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e P and X argumen
23740 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 ts are pointers
23750 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 whose meanings d
23760 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a epend on T..**.*
23770 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 * <dl>.** [[SQLI
23780 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 TE_TRACE_STMT]]
23790 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 <dt>SQLITE_TRACE
237a0 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 _STMT</dt>.** <d
237b0 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 d>^An SQLITE_TRA
237c0 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b CE_STMT callback
237d0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e is invoked when
237e0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 a prepared stat
237f0 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 ement.** first b
23800 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e egins running an
23810 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 d possibly at ot
23820 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67 her times during
23830 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f the.** executio
23840 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 n of the prepare
23850 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 d statement, suc
23860 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61 72 h as at the star
23870 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 t of each.** tri
23880 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e gger subprogram.
23890 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 ^The P argument
238a0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
238b0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
238c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 d statement]. ^T
238d0 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 he X argument is
238e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
238f0 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 string which.**
23900 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65 is the unexpande
23910 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68 d SQL text of th
23920 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
23930 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 ment or an SQL c
23940 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 omment .** that
23950 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69 6e indicates the in
23960 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 vocation of a tr
23970 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c igger. ^The cal
23980 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 lback can comput
23990 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65 e.** the same te
239a0 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 xt that would ha
239b0 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 ve been returned
239c0 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b by the legacy [
239d0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d sqlite3_trace()]
239e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79 .** interface by
239f0 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72 67 using the X arg
23a00 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67 ument when X beg
23a10 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e ins with "--" an
23a20 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 d invoking.** [s
23a30 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f qlite3_expanded_
23a40 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73 sql(P)] otherwis
23a50 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 e..**.** [[SQLIT
23a60 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d E_TRACE_PROFILE]
23a70 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 ] <dt>SQLITE_TRA
23a80 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a CE_PROFILE</dt>.
23a90 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 ** <dd>^An SQLIT
23aa0 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 E_TRACE_PROFILE
23ab0 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 callback provide
23ac0 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 s approximately
23ad0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f the same.** info
23ae0 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72 rmation as is pr
23af0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b 73 ovided by the [s
23b00 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 qlite3_profile()
23b10 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e ] callback..** ^
23b20 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 The P argument i
23b30 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
23b40 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
23b50 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a tement] and the.
23b60 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f ** X argument po
23b70 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74 ints to a 64-bit
23b80 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 integer which i
23b90 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 s the estimated
23ba0 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 of.** the number
23bb0 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 of nanosecond t
23bc0 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 hat the prepared
23bd0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 statement took
23be0 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 to run..** ^The
23bf0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f SQLITE_TRACE_PRO
23c00 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 FILE callback is
23c10 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 invoked when th
23c20 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 e statement fini
23c30 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 shes..**.** [[SQ
23c40 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d LITE_TRACE_ROW]]
23c50 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 <dt>SQLITE_TRAC
23c60 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 E_ROW</dt>.** <d
23c70 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 d>^An SQLITE_TRA
23c80 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 CE_ROW callback
23c90 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 is invoked whene
23ca0 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a ver a prepared.*
23cb0 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 * statement gene
23cc0 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72 rates a single r
23cd0 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a ow of result. .
23ce0 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 ** ^The P argume
23cf0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 nt is a pointer
23d00 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 to the [prepared
23d10 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 statement] and
23d20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e the.** X argumen
23d30 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a t is unused..**.
23d40 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 ** [[SQLITE_TRAC
23d50 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 E_CLOSE]] <dt>SQ
23d60 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 LITE_TRACE_CLOSE
23d70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e </dt>.** <dd>^An
23d80 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c SQLITE_TRACE_CL
23d90 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 OSE callback is
23da0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 invoked when a d
23db0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
23dc0 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a ction closes..**
23dd0 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 ^The P argument
23de0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
23df0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
23e00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 onnection] objec
23e10 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61 t.** and the X a
23e20 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 rgument is unuse
23e30 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 d..** </dl>.*/.#
23e40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 define SQLITE_TR
23e50 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30 ACE_STMT 0
23e60 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 x01.#define SQLI
23e70 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 TE_TRACE_PROFILE
23e80 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 0x02.#define
23e90 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f SQLITE_TRACE_RO
23ea0 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23 64 W 0x04.#d
23eb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 efine SQLITE_TRA
23ec0 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78 CE_CLOSE 0x
23ed0 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 08../*.** CAPI3R
23ee0 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f EF: SQL Trace Ho
23ef0 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ok.** METHOD: sq
23f00 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 lite3.**.** ^The
23f10 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 sqlite3_trace_v
23f20 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 2(D,M,X,P) inter
23f30 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 face registers a
23f40 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a trace callback.
23f50 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 ** function X ag
23f60 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20 ainst [database
23f70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 connection] D, u
23f80 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61 sing property ma
23f90 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 sk M.** and cont
23fa0 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 ext pointer P.
23fb0 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61 ^If the X callba
23fc0 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 ck is.** NULL or
23fd0 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 if the M mask i
23fe0 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 s zero, then tra
23ff0 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 cing is disabled
24000 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 . The.** M argu
24010 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 ment should be t
24020 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64 he bitwise OR-ed
24030 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a combination of.
24040 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 ** zero or more
24050 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 [SQLITE_TRACE] c
24060 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 onstants..**.**
24070 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 ^Each call to ei
24080 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61 ther sqlite3_tra
24090 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f ce() or sqlite3_
240a0 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72 trace_v2() overr
240b0 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c ides .** (cancel
240c0 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c s) any prior cal
240d0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 ls to sqlite3_tr
240e0 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ace() or sqlite3
240f0 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a _trace_v2()..**.
24100 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 ** ^The X callba
24110 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 ck is invoked wh
24120 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68 enever any of th
24130 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66 e events identif
24140 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 ied by .** mask
24150 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69 M occur. ^The i
24160 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76 61 nteger return va
24170 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c lue from the cal
24180 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74 lback is current
24190 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 ly.** ignored, t
241a0 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20 63 hough this may c
241b0 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 hange in future
241c0 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 releases. Callb
241d0 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 ack.** implement
241e0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 ations should re
241f0 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 turn zero to ens
24200 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61 ure future compa
24210 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 tibility..**.**
24220 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 ^A trace callbac
24230 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 k is invoked wit
24240 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 h four arguments
24250 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 : callback(T,C,P
24260 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 ,X)..** ^The T a
24270 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f rgument is one o
24280 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 f the [SQLITE_TR
24290 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 ACE].** constant
242a0 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 s to indicate wh
242b0 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 y the callback w
242c0 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e as invoked..** ^
242d0 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 The C argument i
242e0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
242f0 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e context pointer.
24300 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 .** The P and X
24310 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f arguments are po
24320 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 inters whose mea
24330 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 nings depend on
24340 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c T..**.** The sql
24350 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 ite3_trace_v2()
24360 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 interface is int
24370 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65 ended to replace
24380 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 the legacy.** i
24390 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 nterfaces [sqlit
243a0 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20 e3_trace()] and
243b0 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 [sqlite3_profile
243c0 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 ()], both of whi
243d0 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63 ch.** are deprec
243e0 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ated..*/.int sql
243f0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 ite3_trace_v2(.
24400 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 sqlite3*,. uns
24410 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 igned uMask,. i
24420 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 nt(*xCallback)(u
24430 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f nsigned,void*,vo
24440 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f id*,void*),. vo
24450 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a id *pCtx.);../*.
24460 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 ** CAPI3REF: Que
24470 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c ry Progress Call
24480 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a backs.** METHOD:
24490 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
244a0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 The sqlite3_prog
244b0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e ress_handler(D,N
244c0 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 ,X,P) interface
244d0 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 causes the callb
244e0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ack.** function
244f0 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 X to be invoked
24500 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 periodically dur
24510 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 ing long running
24520 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 calls to.** [sq
24530 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b lite3_exec()], [
24540 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
24550 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 and [sqlite3_get
24560 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a _table()] for.**
24570 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
24580 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d tion D. An exam
24590 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 ple use for this
245a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
245b0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 to keep a GUI u
245c0 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 pdated during a
245d0 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a large query..**.
245e0 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 ** ^The paramete
245f0 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 r P is passed th
24600 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c rough as the onl
24610 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 y parameter to t
24620 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 he .** callback
24630 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 function X. ^Th
24640 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 e parameter N is
24650 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 the approximate
24660 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b number of .** [
24670 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
24680 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 instructions] th
24690 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 at are evaluated
246a0 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 between success
246b0 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f ive.** invocatio
246c0 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 ns of the callba
246d0 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 ck X. ^If N is
246e0 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 less than one th
246f0 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a en the progress.
24700 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 ** handler is di
24710 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f sabled..**.** ^O
24720 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f nly a single pro
24730 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 gress handler ma
24740 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 y be defined at
24750 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 one time per.**
24760 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
24770 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 tion]; setting a
24780 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 new progress ha
24790 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 ndler cancels th
247a0 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e e.** old one. ^
247b0 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 Setting paramete
247c0 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 r X to NULL disa
247d0 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 bles the progres
247e0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 s handler..** ^T
247f0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
24800 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 ler is also disa
24810 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 bled by setting
24820 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 N to a value les
24830 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a s.** than 1..**.
24840 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 ** ^If the progr
24850 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 ess callback ret
24860 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 urns non-zero, t
24870 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a he operation is.
24880 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 ** interrupted.
24890 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 This feature ca
248a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 n be used to imp
248b0 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e lement a.** "Can
248c0 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 cel" button on a
248d0 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 GUI progress di
248e0 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 alog box..**.**
248f0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e The progress han
24900 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 dler callback mu
24910 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 st not do anythi
24920 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 ng that will mod
24930 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 ify.** the datab
24940 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
24950 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
24960 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
24970 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b ..** Note that [
24980 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
24990 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 v2()] and [sqlit
249a0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 e3_step()] both
249b0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 modify their.**
249c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
249d0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 ions for the mea
249e0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 ning of "modify"
249f0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 in this paragra
24a00 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 ph..**.*/.void s
24a10 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
24a20 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a handler(sqlite3*
24a30 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f , int, int(*)(vo
24a40 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f id*), void*);../
24a50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
24a60 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 pening A New Dat
24a70 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
24a80 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a .** CONSTRUCTOR:
24a90 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
24aa0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f These routines o
24ab0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 pen an SQLite da
24ac0 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 tabase file as s
24ad0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
24ae0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 .** filename arg
24af0 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 ument. ^The file
24b00 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 name argument is
24b10 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
24b20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c UTF-8 for.** sql
24b30 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
24b40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
24b50 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 ) and as UTF-16
24b60 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
24b70 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 te.** order for
24b80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
24b90 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 . ^(A [database
24ba0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
24bb0 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a le is usually.**
24bc0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 returned in *pp
24bd0 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 Db, even if an e
24be0 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 rror occurs. Th
24bf0 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e e only exception
24c00 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 is that.** if S
24c10 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 QLite is unable
24c20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f to allocate memo
24c30 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b ry to hold the [
24c40 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c sqlite3] object,
24c50 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 .** a NULL will
24c60 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 be written into
24c70 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 *ppDb instead of
24c80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
24c90 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f e [sqlite3].** o
24ca0 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 bject.)^ ^(If th
24cb0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
24cc0 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 ened (and/or cre
24cd0 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c ated) successful
24ce0 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c ly, then.** [SQL
24cf0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 ITE_OK] is retur
24d00 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 ned. Otherwise
24d10 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
24d20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e is returned.)^ ^
24d30 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f The.** [sqlite3_
24d40 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 errmsg()] or [sq
24d50 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
24d60 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 ] routines can b
24d70 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e e used to obtain
24d80 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c .** an English l
24d90 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 anguage descript
24da0 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 ion of the error
24db0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 following a fai
24dc0 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f lure of any.** o
24dd0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 f the sqlite3_op
24de0 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a en() routines..*
24df0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c *.** ^The defaul
24e00 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 t encoding will
24e10 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 be UTF-8 for dat
24e20 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 abases created u
24e30 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f sing.** sqlite3_
24e40 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 open() or sqlite
24e50 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 3_open_v2(). ^T
24e60 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 he default encod
24e70 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 ing for database
24e80 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 s.** created usi
24e90 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 ng sqlite3_open1
24ea0 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 6() will be UTF-
24eb0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 16 in the native
24ec0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a byte order..**.
24ed0 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f ** Whether or no
24ee0 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 t an error occur
24ef0 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 s when it is ope
24f00 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a ned, resources.*
24f10 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
24f20 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 h the [database
24f30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
24f40 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c le should be rel
24f50 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 eased by.** pass
24f60 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 ing it to [sqlit
24f70 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e e3_close()] when
24f80 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 it is no longer
24f90 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a required..**.**
24fa0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 The sqlite3_ope
24fb0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 n_v2() interface
24fc0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 works like sqli
24fd0 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 te3_open().** ex
24fe0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 cept that it acc
24ff0 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f epts two additio
25000 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 nal parameters f
25010 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f or additional co
25020 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 ntrol.** over th
25030 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 e new database c
25040 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 onnection. ^(Th
25050 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 e flags paramete
25060 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f r to.** sqlite3_
25070 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 open_v2() can ta
25080 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 ke one of.** the
25090 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 following three
250a0 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 values, optiona
250b0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 lly combined wit
250c0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 h the .** [SQLIT
250d0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c E_OPEN_NOMUTEX],
250e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 [SQLITE_OPEN_FU
250f0 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 LLMUTEX], [SQLIT
25100 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
25110 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f HE],.** [SQLITE_
25120 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
25130 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 E], and/or [SQLI
25140 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 TE_OPEN_URI] fla
25150 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e gs:)^.**.** <dl>
25160 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 .** ^(<dt>[SQLIT
25170 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d E_OPEN_READONLY]
25180 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
25190 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
251a0 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 ned in read-only
251b0 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 mode. If the d
251c0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 atabase does not
251d0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 .** already exis
251e0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 t, an error is r
251f0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a eturned.</dd>)^.
25200 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c **.** ^(<dt>[SQL
25210 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
25220 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TE]</dt>.** <dd>
25230 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
25240 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 opened for readi
25250 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 ng and writing i
25260 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 f possible, or r
25270 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 eading.** only i
25280 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 f the file is wr
25290 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 ite protected by
252a0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
252b0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 ystem. In eithe
252c0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 r.** case the da
252d0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 tabase must alre
252e0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 ady exist, other
252f0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 wise an error is
25300 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 returned.</dd>)
25310 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 ^.**.** ^(<dt>[S
25320 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
25330 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f RITE] | [SQLITE_
25340 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 OPEN_CREATE]</dt
25350 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 >.** <dd>The dat
25360 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
25370 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
25380 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 writing, and is
25390 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 created if.** it
253a0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 does not alread
253b0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 y exist. This is
253c0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 the behavior th
253d0 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 at is always use
253e0 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 d for.** sqlite3
253f0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 _open() and sqli
25400 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 te3_open16().</d
25410 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a d>)^.** </dl>.**
25420 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 .** If the 3rd p
25430 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
25440 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
25450 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a not one of the.
25460 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 ** combinations
25470 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 shown above opti
25480 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 onally combined
25490 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 with other.** [S
254a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
254b0 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 NLY | SQLITE_OPE
254c0 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 N_* bits].** the
254d0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
254e0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
254f0 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 ** ^If the [SQLI
25500 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d TE_OPEN_NOMUTEX]
25510 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 flag is set, th
25520 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
25530 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 connection.** op
25540 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 ens in the multi
25550 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 -thread [threadi
25560 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 ng mode] as long
25570 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 as the single-t
25580 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 hread.** mode ha
25590 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 s not been set a
255a0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f t compile-time o
255b0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e r start-time. ^
255c0 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 If the.** [SQLIT
255d0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
255e0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 ] flag is set th
255f0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
25600 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 connection opens
25610 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 .** in the seria
25620 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
25630 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 mode] unless si
25640 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a ngle-thread was.
25650 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 ** previously se
25660 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c lected at compil
25670 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d e-time or start-
25680 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 time..** ^The [S
25690 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
256a0 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 DCACHE] flag cau
256b0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ses the database
256c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 connection to b
256d0 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f e.** eligible to
256e0 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 use [shared cac
256f0 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 he mode], regard
25700 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
25710 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a or not shared.**
25720 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 cache is enable
25730 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
25740 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 _enable_shared_c
25750 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a ache()]. ^The.*
25760 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 * [SQLITE_OPEN_P
25770 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 RIVATECACHE] fla
25780 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 g causes the dat
25790 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
257a0 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 to not.** parti
257b0 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 cipate in [share
257c0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 d cache mode] ev
257d0 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 en if it is enab
257e0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 led..**.** ^The
257f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
25800 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
25810 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d _v2() is the nam
25820 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c e of the.** [sql
25830 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
25840 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 that defines th
25850 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
25860 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 em interface tha
25870 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 t.** the new dat
25880 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
25890 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 should use. ^I
258a0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
258b0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e ameter is.** a N
258c0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
258d0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 the default [sq
258e0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
258f0 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a t is used..**.**
25900 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d ^If the filenam
25910 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c e is ":memory:",
25920 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c then a private,
25930 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 temporary in-me
25940 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a mory database.**
25950 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 is created for
25960 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 the connection.
25970 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 ^This in-memory
25980 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 database will v
25990 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 anish when.** th
259a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
259b0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e ction is closed.
259c0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e Future version
259d0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 s of SQLite migh
259e0 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 t.** make use of
259f0 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 additional spec
25a00 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 ial filenames th
25a10 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 at begin with th
25a20 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e e ":" character.
25a30 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d .** It is recomm
25a40 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 ended that when
25a50 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e a database filen
25a60 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 ame actually doe
25a70 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 s begin with.**
25a80 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 a ":" character
25a90 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 you should prefi
25aa0 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 x the filename w
25ab0 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 ith a pathname s
25ac0 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 uch as.** "./" t
25ad0 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 o avoid ambiguit
25ae0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 y..**.** ^If the
25af0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 filename is an
25b00 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 empty string, th
25b10 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 en a private, te
25b20 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 mporary.** on-di
25b30 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c sk database will
25b40 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 be created. ^T
25b50 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 his private data
25b60 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 base will be.**
25b70 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 automatically de
25b80 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 leted as soon as
25b90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
25ba0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 nnection is clos
25bb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 ed..**.** [[URI
25bc0 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c filenames in sql
25bd0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 ite3_open()]] <h
25be0 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 3>URI Filenames<
25bf0 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b /h3>.**.** ^If [
25c00 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e URI filename] in
25c10 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 terpretation is
25c20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 enabled, and the
25c30 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
25c40 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 nt.** begins wit
25c50 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 h "file:", then
25c60 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
25c70 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
25c80 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 URI. ^URI.** fi
25c90 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 lename interpret
25ca0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 ation is enabled
25cb0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f if the [SQLITE_
25cc0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 OPEN_URI] flag i
25cd0 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 s.** set in the
25ce0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 third argument t
25cf0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
25d00 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 2(), or if it ha
25d10 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 s.** been enable
25d20 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 d globally using
25d30 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e the [SQLITE_CON
25d40 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 FIG_URI] option
25d50 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c with the.** [sql
25d60 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d ite3_config()] m
25d70 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 ethod or by the
25d80 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d [SQLITE_USE_URI]
25d90 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
25da0 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69 6c tion..** URI fil
25db0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 ename interpreta
25dc0 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f tion is turned o
25dd0 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 ff.** by default
25de0 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c , but future rel
25df0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 eases of SQLite
25e00 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 might enable URI
25e10 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 filename.** int
25e20 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 erpretation by d
25e30 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 efault. See "[U
25e40 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 RI filenames]" f
25e50 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a or additional.**
25e60 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
25e70 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 .** URI filename
25e80 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 s are parsed acc
25e90 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 ording to RFC 39
25ea0 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 86. ^If the URI
25eb0 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 contains an.** a
25ec0 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 uthority, then i
25ed0 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 t must be either
25ee0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
25ef0 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a or the string .
25f00 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 ** "localhost".
25f10 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 ^If the authorit
25f20 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 y is not an empt
25f30 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 y string or "loc
25f40 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 alhost", an .**
25f50 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 error is returne
25f60 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e d to the caller.
25f70 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 ^The fragment c
25f80 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 omponent of a UR
25f90 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e I, if .** presen
25fa0 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a t, is ignored..*
25fb0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 *.** ^SQLite use
25fc0 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f s the path compo
25fd0 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 nent of the URI
25fe0 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 as the name of t
25ff0 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 he disk file.**
26000 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 which contains t
26010 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 he database. ^If
26020 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 the path begins
26030 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 with a '/' char
26040 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 acter, .** then
26050 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 it is interprete
26060 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 d as an absolute
26070 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 path. ^If the p
26080 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 ath does not beg
26090 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f in .** with a '/
260a0 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 ' (meaning that
260b0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 the authority se
260c0 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 ction is omitted
260d0 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a from the URI).*
260e0 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 * then the path
260f0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
26100 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 s a relative pat
26110 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 h. .** ^(On wind
26120 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 ows, the first c
26130 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 omponent of an a
26140 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a bsolute path .**
26150 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 is a drive spec
26160 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 ification (e.g.
26170 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b "C:").)^.**.** [
26180 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 [core URI query
26190 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 parameters]].**
261a0 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e The query compon
261b0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 ent of a URI may
261c0 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 contain paramet
261d0 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 ers that are int
261e0 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 erpreted.** eith
261f0 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 er by SQLite its
26200 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 elf, or by a [VF
26210 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 S | custom VFS i
26220 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a mplementation]..
26230 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 ** SQLite and it
26240 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 s built-in [VFSe
26250 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 s] interpret the
26260 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 .** following qu
26270 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a ery parameters:.
26280 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 **.** <ul>.**
26290 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a <li> <b>vfs</b>:
262a0 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 ^The "vfs" para
262b0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 meter may be use
262c0 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 d to specify the
262d0 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 name of.**
262e0 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 a VFS object tha
262f0 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f t provides the o
26300 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
26310 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 interface that s
26320 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 hould.** be
26330 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 used to access t
26340 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
26350 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 on disk. ^If th
26360 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 is option is set
26370 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d to.** an em
26380 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 pty string the d
26390 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 efault VFS objec
263a0 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 t is used. ^Spec
263b0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 ifying an unknow
263c0 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 n.** VFS is
263d0 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 an error. ^If sq
263e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
263f0 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 is used and the
26400 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a vfs option is.**
26410 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 present, th
26420 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 en the VFS speci
26430 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 fied by the opti
26440 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 on takes precede
26450 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 nce over.**
26460 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 the value passed
26470 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 as the fourth p
26480 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
26490 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a te3_open_v2()..*
264a0 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d *.** <li> <b>m
264b0 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d ode</b>: ^(The m
264c0 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 ode parameter ma
264d0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 y be set to eith
264e0 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a er "ro", "rw",.*
264f0 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 * "rwc", or
26500 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 "memory". Attemp
26510 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 ting to set it t
26520 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 o any other valu
26530 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 e is.** an e
26540 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 rror)^. .**
26550 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 ^If "ro" is spec
26560 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 ified, then the
26570 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
26580 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 ed for read-only
26590 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c .** access,
265a0 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 just as if the
265b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
265c0 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 DONLY] flag had
265d0 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 been set in the
265e0 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 .** third ar
265f0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
26600 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 3_open_v2(). ^If
26610 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e the mode option
26620 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 is set to .**
26630 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 "rw", then th
26640 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
26650 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 ened for read-wr
26660 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 ite (but not cre
26670 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 ate) .** acc
26680 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 ess, as if SQLIT
26690 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
266a0 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 (but not SQLITE
266b0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 _OPEN_CREATE) ha
266c0 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 d .** been s
266d0 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 et. ^Value "rwc"
266e0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 is equivalent t
266f0 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a o setting both .
26700 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 ** SQLITE_OP
26710 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 EN_READWRITE and
26720 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 SQLITE_OPEN_CRE
26730 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f ATE. ^If the mo
26740 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 de option is.**
26750 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f set to "memo
26760 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 ry" then a pure
26770 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 [in-memory datab
26780 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 ase] that never
26790 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 reads.** or
267a0 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b writes from disk
267b0 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 is used. ^It is
267c0 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 an error to spe
267d0 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 cify a value for
267e0 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 .** the mode
267f0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 parameter that
26800 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 is less restrict
26810 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 ive than that sp
26820 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 ecified by.**
26830 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 the flags pass
26840 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 ed in the third
26850 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
26860 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a ite3_open_v2()..
26870 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e **.** <li> <b>
26880 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 cache</b>: ^The
26890 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 cache parameter
268a0 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 may be set to ei
268b0 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 ther "shared" or
268c0 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 .** "private
268d0 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 ". ^Setting it t
268e0 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 o "shared" is eq
268f0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 uivalent to sett
26900 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 ing the.** S
26910 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
26920 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 DCACHE bit in th
26930 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
26940 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 passed to.**
26950 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 sqlite3_open_v
26960 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 2(). ^Setting th
26970 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 e cache paramete
26980 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 r to "private" i
26990 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 s .** equiva
269a0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 lent to setting
269b0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f the SQLITE_OPEN_
269c0 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 PRIVATECACHE bit
269d0 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c ..** ^If sql
269e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
269f0 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 s used and the "
26a00 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 cache" parameter
26a10 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a is present in.*
26a20 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 * a URI file
26a30 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 name, its value
26a40 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 overrides any be
26a50 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 havior requested
26a60 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 by setting.**
26a70 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 SQLITE_OPEN_P
26a80 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 RIVATECACHE or S
26a90 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
26aa0 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a DCACHE flag..**.
26ab0 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 ** <li> <b>psow
26ac0 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 </b>: ^The psow
26ad0 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 parameter indica
26ae0 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e tes whether or n
26af0 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 ot the.** [p
26b00 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 owersafe overwri
26b10 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 te] property doe
26b20 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 s or does not ap
26b30 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 ply to the.**
26b40 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 storage media
26b50 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74 on which the dat
26b60 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 abase file resid
26b70 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 es..**.** <li>
26b80 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e <b>nolock</b>: ^
26b90 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d The nolock param
26ba0 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 eter is a boolea
26bb0 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 n query paramete
26bc0 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 r.** which i
26bd0 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 f set disables f
26be0 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 ile locking in r
26bf0 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 ollback journal
26c00 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 modes. This.**
26c10 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f is useful fo
26c20 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 r accessing a da
26c30 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 tabase on a file
26c40 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 system that does
26c50 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 not.** supp
26c60 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 ort locking. Ca
26c70 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 ution: Database
26c80 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 corruption migh
26c90 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a t result if two.
26ca0 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 ** or more p
26cb0 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74 rocesses write t
26cc0 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 o the same datab
26cd0 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 ase and any one
26ce0 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 of those.**
26cf0 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e processes uses n
26d00 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 olock=1..**.**
26d10 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c <li> <b>immutabl
26d20 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 e</b>: ^The immu
26d30 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 table parameter
26d40 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 is a boolean que
26d50 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 ry.** parame
26d60 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 ter that indicat
26d70 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 es that the data
26d80 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f base file is sto
26d90 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 red on.** re
26da0 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 ad-only media.
26db0 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 ^When immutable
26dc0 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 is set, SQLite a
26dd0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a ssumes that the.
26de0 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20 ** database
26df0 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 file cannot be c
26e00 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 hanged, even by
26e10 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 a process with h
26e20 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 igher.** pri
26e30 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 vilege, and so t
26e40 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
26e50 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 pened read-only
26e60 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a and all locking.
26e70 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 ** and chang
26e80 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 e detection is d
26e90 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f isabled. Cautio
26ea0 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 n: Setting the i
26eb0 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 mmutable.**
26ec0 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 property on a da
26ed0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 tabase file that
26ee0 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 does in fact ch
26ef0 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a ange can result.
26f00 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 ** in incorr
26f10 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 ect query result
26f20 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 s and/or [SQLITE
26f30 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 _CORRUPT] errors
26f40 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 ..** See als
26f50 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 o: [SQLITE_IOCAP
26f60 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 _IMMUTABLE]..**
26f70 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a .** </ul>.
26f80 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e **.** ^Specifyin
26f90 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 g an unknown par
26fa0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 ameter in the qu
26fb0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 ery component of
26fc0 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e a URI is not an
26fd0 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 .** error. Futu
26fe0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
26ff0 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 QLite might unde
27000 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 rstand additiona
27010 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d l query.** param
27020 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 eters. See "[qu
27030 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 ery parameters w
27040 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e ith special mean
27050 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 ing to SQLite]"
27060 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 for.** additiona
27070 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
27080 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e *.** [[URI filen
27090 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c ame examples]] <
270a0 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 h3>URI filename
270b0 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a examples</h3>.**
270c0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 .** <table borde
270d0 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 r="1" align=cent
270e0 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 er cellpadding=5
270f0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 >.** <tr><th> UR
27100 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e I filenames <th>
27110 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e Results.** <tr>
27120 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 <td> file:data.d
27130 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 b <td> .**
27140 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c Open the fil
27150 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 e "data.db" in t
27160 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 he current direc
27170 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 tory..** <tr><td
27180 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 > file:/home/fre
27190 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a d/data.db<br>.**
271a0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f file:/
271b0 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 //home/fred/data
271c0 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 .db <br> .**
271d0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 file://loc
271e0 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 alhost/home/fred
271f0 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 /data.db <br> <t
27200 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
27210 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 Open the databas
27220 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 e file "/home/fr
27230 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 ed/data.db"..**
27240 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f <tr><td> file://
27250 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 darkstar/home/fr
27260 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 ed/data.db <td>
27270 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 .** An
27280 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 error. "darkstar
27290 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 " is not a recog
272a0 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e nized authority.
272b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c .** <tr><td styl
272c0 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e e="white-space:n
272d0 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 owrap"> .**
272e0 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f file:///C:/
272f0 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 Documents%20and%
27300 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 20Settings/fred/
27310 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a Desktop/data.db.
27320 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 ** <td> Wind
27330 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 ows only: Open t
27340 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 he file "data.db
27350 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b " on fred's desk
27360 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 top on drive.**
27370 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 C:. Not
27380 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 e that the %20 e
27390 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 scaping in this
273a0 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 example is not s
273b0 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 trictly .**
273c0 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d necessary -
273d0 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 space character
273e0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 s can be used li
273f0 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 terally.**
27400 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e in URI filen
27410 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 ames..** <tr><td
27420 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d > file:data.db?m
27430 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 ode=ro&cache=pri
27440 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 vate <td> .**
27450 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 Open file
27460 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 "data.db" in th
27470 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 e current direct
27480 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c ory for read-onl
27490 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 y access..**
274a0 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 Regardless
274b0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
274c0 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 ot shared-cache
274d0 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 mode is enabled
274e0 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 by.** d
274f0 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 efault, use a pr
27500 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 ivate cache..**
27510 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 <tr><td> file:/h
27520 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
27530 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c ?vfs=unix-dotfil
27540 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 e <td>.**
27550 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 Open file "/h
27560 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
27570 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 ". Use the speci
27580 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 al VFS "unix-dot
27590 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 file".**
275a0 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d that uses dot-
275b0 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f files in place o
275c0 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 f posix advisory
275d0 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 locking..** <tr
275e0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e ><td> file:data.
275f0 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 db?mode=readonly
27600 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
27610 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 An error. "re
27620 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 adonly" is not a
27630 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f valid option fo
27640 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 r the "mode" par
27650 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 ameter..** </tab
27660 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 le>.**.** ^URI h
27670 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 exadecimal escap
27680 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 e sequences (%HH
27690 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 ) are supported
276a0 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 within the path
276b0 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d and.** query com
276c0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 ponents of a URI
276d0 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 . A hexadecimal
276e0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 escape sequence
276f0 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a consists of a.**
27700 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 percent sign -
27710 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 "%" - followed b
27720 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 y exactly two he
27730 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 xadecimal digits
27740 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 .** specifying
27750 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 an octet value.
27760 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 ^Before the path
27770 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e or query compon
27780 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 ents of a.** URI
27790 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e filename are in
277a0 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 terpreted, they
277b0 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e are encoded usin
277c0 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 g UTF-8 and all
277d0 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 .** hexadecimal
277e0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 escape sequences
277f0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 replaced by a s
27800 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 ingle byte conta
27810 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 ining the.** cor
27820 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 responding octet
27830 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 . If this proces
27840 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 s generates an i
27850 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 nvalid UTF-8 enc
27860 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 oding,.** the re
27870 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
27880 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f ned..**.** <b>No
27890 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 te to Windows us
278a0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e ers:</b> The en
278b0 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 coding used for
278c0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 the filename arg
278d0 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 ument.** of sqli
278e0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 te3_open() and s
278f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
27900 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 must be UTF-8,
27910 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 not whatever.**
27920 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 codepage is curr
27930 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 ently defined.
27940 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 Filenames contai
27950 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e ning internation
27960 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 al.** characters
27970 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 must be convert
27980 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f ed to UTF-8 prio
27990 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 r to passing the
279a0 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 m into.** sqlite
279b0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 3_open() or sqli
279c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a te3_open_v2()..*
279d0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 *.** <b>Note to
279e0 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 Windows Runtime
279f0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 users:</b> The
27a00 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 temporary direct
27a10 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a ory must be set.
27a20 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c ** prior to call
27a30 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ing sqlite3_open
27a40 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 () or sqlite3_op
27a50 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 en_v2(). Otherw
27a60 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 ise, various.**
27a70 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 features that re
27a80 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 quire the use of
27a90 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 temporary files
27aa0 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a may fail..**.**
27ab0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
27ac0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f te3_temp_directo
27ad0 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ry].*/.int sqlit
27ae0 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 e3_open(. const
27af0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c char *filename,
27b00 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 /* Database f
27b10 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 ilename (UTF-8)
27b20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 */. sqlite3 **p
27b30 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 pDb /*
27b40 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 OUT: SQLite db h
27b50 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 andle */.);.int
27b60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a sqlite3_open16(.
27b70 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 const void *fi
27b80 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
27b90 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
27ba0 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c UTF-16) */. sql
27bb0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 ite3 **ppDb
27bc0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c /* OUT: SQL
27bd0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f ite db handle */
27be0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
27bf0 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 open_v2(. const
27c00 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c char *filename,
27c10 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 /* Database f
27c20 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 ilename (UTF-8)
27c30 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 */. sqlite3 **p
27c40 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 pDb, /*
27c50 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 OUT: SQLite db h
27c60 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 andle */. int f
27c70 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 lags,
27c80 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 /* Flags */.
27c90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 const char *zVf
27ca0 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 s /* Name
27cb0 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 of VFS module t
27cc0 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a o use */.);../*.
27cd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
27ce0 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 ain Values For U
27cf0 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a RI Parameters.**
27d00 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 .** These are ut
27d10 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 ility routines,
27d20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d useful to VFS im
27d30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 plementations, t
27d40 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 hat check.** to
27d50 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73 see if a databas
27d60 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 e file was a URI
27d70 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 that contained
27d80 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79 a specific query
27d90 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 .** parameter,
27da0 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e and if so obtain
27db0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 s the value of t
27dc0 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 hat query parame
27dd0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 ter..**.** If F
27de0 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 is the database
27df0 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 filename pointer
27e00 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 passed into the
27e10 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 xOpen() method
27e20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 of .** a VFS imp
27e30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e lementation when
27e40 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d the flags param
27e50 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 eter to xOpen()
27e60 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d has one or .** m
27e70 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 ore of the [SQLI
27e80 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 TE_OPEN_URI] or
27e90 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 [SQLITE_OPEN_MAI
27ea0 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 N_DB] bits set a
27eb0 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e nd.** P is the n
27ec0 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 ame of the query
27ed0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e parameter, then
27ee0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f .** sqlite3_uri_
27ef0 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 parameter(F,P) r
27f00 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 eturns the value
27f10 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 of the P.** par
27f20 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69 ameter if it exi
27f30 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f sts or a NULL po
27f40 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 inter if P does
27f50 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20 not appear as a
27f60 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 .** query parame
27f70 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 ter on F. If P
27f80 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d is a query param
27f90 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 eter of F.** has
27fa0 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c no explicit val
27fb0 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ue, then sqlite3
27fc0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 _uri_parameter(F
27fd0 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 ,P) returns.** a
27fe0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 pointer to an e
27ff0 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a mpty string..**.
28000 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 ** The sqlite3_u
28010 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
28020 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 ) routine assume
28030 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f s that P is a bo
28040 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 olean.** paramet
28050 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 er and returns t
28060 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 rue (1) or false
28070 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 (0) according t
28080 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f o the value.** o
28090 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 f P. The sqlite
280a0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 3_uri_boolean(F,
280b0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 P,B) routine ret
280c0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 urns true (1) if
280d0 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 the.** value of
280e0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
280f0 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 P is one of "ye
28100 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 s", "true", or "
28110 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 on" in any.** ca
28120 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c se or if the val
28130 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 ue begins with a
28140 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 non-zero number
28150 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 . The .** sqlit
28160 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
28170 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 ,P,B) routines r
28180 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 eturns false (0)
28190 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 if the value of
281a0 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 .** query parame
281b0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 ter P is one of
281c0 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f "no", "false", o
281d0 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 r "off" in any c
281e0 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 ase or.** if the
281f0 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 value begins wi
28200 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 th a numeric zer
28210 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 o. If P is not
28220 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d a query.** param
28230 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 eter on F or if
28240 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 the value of P i
28250 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 s does not match
28260 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 any of the.** a
28270 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 bove, then sqlit
28280 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
28290 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 ,P,B) returns (B
282a0 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 !=0)..**.** The
282b0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 sqlite3_uri_int6
282c0 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 4(F,P,D) routine
282d0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 converts the va
282e0 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a lue of P into a.
282f0 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 ** 64-bit signed
28300 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 integer and ret
28310 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 urns that intege
28320 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 r, or D if P doe
28330 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 s not.** exist.
28340 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 If the value of
28350 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 P is something
28360 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e other than an in
28370 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a teger, then.** z
28380 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e ero is returned.
28390 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 .** .** If F is
283a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
283b0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 then sqlite3_uri
283c0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 _parameter(F,P)
283d0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 returns NULL and
283e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f .** sqlite3_uri_
283f0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 boolean(F,P,B) r
28400 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 eturns B. If F
28410 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f is not a NULL po
28420 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 inter and.** is
28430 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 not a database f
28440 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 ile pathname poi
28450 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 nter that SQLite
28460 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 passed into the
28470 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 xOpen.** VFS me
28480 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 thod, then the b
28490 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 ehavior of this
284a0 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 routine is undef
284b0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c ined and probabl
284c0 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 y.** undesirable
284d0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 ..*/.const char
284e0 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 *sqlite3_uri_par
284f0 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 ameter(const cha
28500 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f r *zFilename, co
28510 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d nst char *zParam
28520 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 );.int sqlite3_u
28530 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 ri_boolean(const
28540 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f char *zFile, co
28550 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d nst char *zParam
28560 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b , int bDefault);
28570 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
28580 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 qlite3_uri_int64
28590 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f (const char*, co
285a0 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 nst char*, sqlit
285b0 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a e3_int64);.../*.
285c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 ** CAPI3REF: Err
285d0 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 or Codes And Mes
285e0 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a sages.** METHOD:
285f0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
28600 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
28610 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 nt sqlite3_* API
28620 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 call associated
28630 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 with .** [datab
28640 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
28650 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 D failed, then t
28660 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f he sqlite3_errco
28670 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a de(D) interface.
28680 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ** returns the n
28690 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 umeric [result c
286a0 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 ode] or [extende
286b0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 d result code] f
286c0 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 or that.** API c
286d0 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d all..** If the m
286e0 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 ost recent API c
286f0 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 all was successf
28700 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 ul,.** then the
28710 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f return value fro
28720 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 m sqlite3_errcod
28730 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 e() is undefined
28740 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
28750 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 3_extended_errco
28760 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 de().** interfac
28770 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 e is the same ex
28780 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 cept that it alw
28790 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 ays returns the
287a0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 .** [extended re
287b0 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 sult code] even
287c0 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 when extended re
287d0 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a sult codes are.*
287e0 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a * disabled..**.*
287f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
28800 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 rrmsg() and sqli
28810 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 te3_errmsg16() r
28820 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 eturn English-la
28830 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 nguage.** text t
28840 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 hat describes th
28850 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 e error, as eith
28860 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d er UTF-8 or UTF-
28870 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 16 respectively.
28880 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 .** ^(Memory to
28890 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d hold the error m
288a0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 essage string is
288b0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 managed interna
288c0 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c lly..** The appl
288d0 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 ication does not
288e0 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 need to worry a
288f0 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 bout freeing the
28900 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 result..** Howe
28910 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 ver, the error s
28920 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f tring might be o
28930 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 verwritten or de
28940 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 allocated by.**
28950 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
28960 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 to other SQLite
28970 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 interface funct
28980 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 ions.)^.**.** ^T
28990 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 he sqlite3_errst
289a0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 r() interface re
289b0 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 turns the Englis
289c0 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a h-language text.
289d0 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65 ** that describe
289e0 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f s the [result co
289f0 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a de], as UTF-8..*
28a00 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f * ^(Memory to ho
28a10 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 ld the error mes
28a20 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d sage string is m
28a30 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c anaged internall
28a40 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f y.** and must no
28a50 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68 t be freed by th
28a60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e e application)^.
28a70 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
28a80 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 serialized [thre
28a90 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 ading mode] is i
28aa0 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 n use, it might
28ab0 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 be the.** case t
28ac0 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 hat a second err
28ad0 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 or occurs on a s
28ae0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 eparate thread i
28af0 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 n between.** the
28b00 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 time of the fir
28b10 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 st error and the
28b20 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 call to these i
28b30 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 nterfaces..** Wh
28b40 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c en that happens,
28b50 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f the second erro
28b60 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 r will be report
28b70 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a ed since these.*
28b80 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 * interfaces alw
28b90 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d ays report the m
28ba0 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c ost recent resul
28bb0 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 t. To avoid.**
28bc0 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 this, each threa
28bd0 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 d can obtain exc
28be0 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 lusive use of th
28bf0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
28c00 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 ection] D.** by
28c10 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 invoking [sqlite
28c20 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 3_mutex_enter]([
28c30 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 sqlite3_db_mutex
28c40 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 ](D)) before beg
28c50 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 inning.** to use
28c60 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 D and invoking
28c70 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c [sqlite3_mutex_l
28c80 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 eave]([sqlite3_d
28c90 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 b_mutex](D)) aft
28ca0 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 er.** all calls
28cb0 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 to the interface
28cc0 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 s listed here ar
28cd0 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a e completed..**.
28ce0 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 ** If an interfa
28cf0 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 ce fails with SQ
28d00 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 LITE_MISUSE, tha
28d10 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 t means the inte
28d20 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 rface.** was inv
28d30 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 oked incorrectly
28d40 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 by the applicat
28d50 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 ion. In that ca
28d60 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 se, the.** error
28d70 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 code and messag
28d80 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 e may or may not
28d90 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 be set..*/.int
28da0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
28db0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e sqlite3 *db);.in
28dc0 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 t sqlite3_extend
28dd0 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 ed_errcode(sqlit
28de0 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 e3 *db);.const c
28df0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 har *sqlite3_err
28e00 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 msg(sqlite3*);.c
28e10 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
28e20 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 e3_errmsg16(sqli
28e30 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 te3*);.const cha
28e40 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 r *sqlite3_errst
28e50 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 r(int);../*.** C
28e60 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 API3REF: Prepare
28e70 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 d Statement Obje
28e80 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ct.** KEYWORDS:
28e90 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d {prepared statem
28ea0 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 ent} {prepared s
28eb0 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a tatements}.**.**
28ec0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
28ed0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 this object repr
28ee0 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 esents a single
28ef0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 SQL statement th
28f00 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 at.** has been c
28f10 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e ompiled into bin
28f20 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 ary form and is
28f30 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c ready to be eval
28f40 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 uated..**.** Thi
28f50 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73 nk of each SQL s
28f60 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65 tatement as a se
28f70 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20 parate computer
28f80 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a program. The.**
28f90 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 original SQL te
28fa0 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64 xt is source cod
28fb0 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 73 e. A prepared s
28fc0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 tatement object
28fd0 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69 .** is the compi
28fe0 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e led object code.
28ff0 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 All SQL must b
29000 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f e converted into
29010 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 a.** prepared s
29020 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 tatement before
29030 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a it can be run..*
29040 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 *.** The life-cy
29050 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 cle of a prepare
29060 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 d statement obje
29070 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 ct usually goes
29080 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a like this:.**.**
29090 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 <ol>.** <li> Cr
290a0 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72 65 eate the prepare
290b0 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 d statement obje
290c0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ct using [sqlite
290d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 3_prepare_v2()].
290e0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 .** <li> Bind va
290f0 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 lues to [paramet
29100 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 ers] using the s
29110 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a qlite3_bind_*().
29120 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 ** interfac
29130 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 es..** <li> Run
29140 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 the SQL by calli
29150 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ng [sqlite3_step
29160 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 ()] one or more
29170 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 times..** <li> R
29180 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 eset the prepare
29190 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e d statement usin
291a0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
291b0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b ()] then go back
291c0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 .** to step
291d0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 2. Do this zer
291e0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e o or more times.
291f0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 .** <li> Destroy
29200 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e the object usin
29210 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
29220 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e ize()]..** </ol>
29230 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
29240 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ct sqlite3_stmt
29250 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f sqlite3_stmt;../
29260 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
29270 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a un-time Limits.*
29280 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
29290 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 3.**.** ^(This i
292a0 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 nterface allows
292b0 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 the size of vari
292c0 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 ous constructs t
292d0 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 o be limited.**
292e0 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 on a connection
292f0 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 by connection ba
29300 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 sis. The first
29310 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
29320 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
29330 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 nnection] whose
29340 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 limit is to be s
29350 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 et or queried.
29360 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 The.** second pa
29370 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f rameter is one o
29380 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 f the [limit cat
29390 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 egories] that de
293a0 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 fine a.** class
293b0 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f of constructs to
293c0 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 be size limited
293d0 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 . The third par
293e0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a ameter is the.**
293f0 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 new limit for t
29400 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e hat construct.)^
29410 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e .**.** ^If the n
29420 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 ew limit is a ne
29430 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 gative number, t
29440 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 he limit is unch
29450 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 anged..** ^(For
29460 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 each limit categ
29470 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ory SQLITE_LIMIT
29480 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 _<i>NAME</i> the
29490 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d re is a .** [lim
294a0 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 its | hard upper
294b0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 bound].** set a
294c0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 t compile-time b
294d0 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 y a C preprocess
294e0 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a or macro called.
294f0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c ** [limits | SQL
29500 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c ITE_MAX_<i>NAME<
29510 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f /i>]..** (The "_
29520 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e LIMIT_" in the n
29530 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 ame is changed t
29540 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a o "_MAX_".))^.**
29550 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e ^Attempts to in
29560 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 crease a limit a
29570 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 bove its hard up
29580 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a per bound are.**
29590 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 silently trunca
295a0 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 ted to the hard
295b0 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a upper bound..**.
295c0 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f ** ^Regardless o
295d0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
295e0 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 the limit was c
295f0 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 hanged, the .**
29600 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 [sqlite3_limit()
29610 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
29620 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 rns the prior va
29630 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 lue of the limit
29640 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 ..** ^Hence, to
29650 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 find the current
29660 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 value of a limi
29670 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 t without changi
29680 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 ng it,.** simply
29690 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 invoke this int
296a0 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 erface with the
296b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
296c0 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a set to -1..**.**
296d0 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 Run-time limits
296e0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
296f0 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 r use in applica
29700 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 tions that manag
29710 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 e.** both their
29720 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 own internal dat
29730 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 abase and also d
29740 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 atabases that ar
29750 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 e controlled.**
29760 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 by untrusted ext
29770 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 ernal sources.
29780 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 An example appli
29790 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 cation might be
297a0 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 a.** web browser
297b0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 that has its ow
297c0 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 n databases for
297d0 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 storing history
297e0 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 and.** separate
297f0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f databases contro
29800 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 lled by JavaScri
29810 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 pt applications
29820 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 downloaded.** of
29830 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 f the Internet.
29840 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 The internal da
29850 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 tabases can be g
29860 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 iven the.** larg
29870 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 e, default limit
29880 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 s. Databases ma
29890 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 naged by externa
298a0 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a l sources can.**
298b0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 be given much s
298c0 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 maller limits de
298d0 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e signed to preven
298e0 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 t a denial of se
298f0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e rvice.** attack.
29900 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 Developers mig
29910 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 ht also want to
29920 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 use the [sqlite3
29930 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
29940 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 )].** interface
29950 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 to further contr
29960 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c ol untrusted SQL
29970 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 . The size of t
29980 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 he database.** c
29990 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 reated by an unt
299a0 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 rusted script ca
299b0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 n be contained u
299c0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 sing the.** [max
299d0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 _page_count] [PR
299e0 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 AGMA]..**.** New
299f0 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 run-time limit
29a00 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 categories may b
29a10 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
29a20 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 e releases..*/.i
29a30 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 nt sqlite3_limit
29a40 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 (sqlite3*, int i
29a50 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a d, int newVal);.
29a60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
29a70 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 Run-Time Limit
29a80 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 Categories.** KE
29a90 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 YWORDS: {limit c
29aa0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 ategory} {*limit
29ab0 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a categories}.**.
29ac0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
29ad0 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 ts define variou
29ae0 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 s performance li
29af0 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e mits.** that can
29b00 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 be lowered at r
29b10 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 un-time using [s
29b20 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e qlite3_limit()].
29b30 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 .** The synopsis
29b40 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 of the meanings
29b50 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 of the various
29b60 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 limits is shown
29b70 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 below..** Additi
29b80 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
29b90 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 is available at
29ba0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 [limits | Limit
29bb0 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a s in SQLite]..**
29bc0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 .** <dl>.** [[SQ
29bd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
29be0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 H]] ^(<dt>SQLITE
29bf0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 _LIMIT_LENGTH</d
29c00 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
29c10 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e ximum size of an
29c20 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 y string or BLOB
29c30 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 or table row, i
29c40 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a n bytes.<dd>)^.*
29c50 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
29c60 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d MIT_SQL_LENGTH]]
29c70 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
29c80 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f MIT_SQL_LENGTH</
29c90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
29ca0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
29cb0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
29cc0 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 t, in bytes.</dd
29cd0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
29ce0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d TE_LIMIT_COLUMN]
29cf0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
29d00 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e IMIT_COLUMN</dt>
29d10 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
29d20 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f mum number of co
29d30 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 lumns in a table
29d40 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 definition or i
29d50 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 n the.** result
29d60 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 set of a [SELECT
29d70 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d ] or the maximum
29d80 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
29d90 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a ns in an index.*
29da0 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 * or in an ORDER
29db0 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 BY or GROUP BY
29dc0 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a clause.</dd>)^.*
29dd0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
29de0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d MIT_EXPR_DEPTH]]
29df0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
29e00 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f MIT_EXPR_DEPTH</
29e10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
29e20 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 aximum depth of
29e30 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f the parse tree o
29e40 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e n any expression
29e50 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
29e60 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f [SQLITE_LIMIT_CO
29e70 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 MPOUND_SELECT]]
29e80 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
29e90 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 IT_COMPOUND_SELE
29ea0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 CT</dt>.** <dd>T
29eb0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
29ec0 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 r of terms in a
29ed0 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 compound SELECT
29ee0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 statement.</dd>)
29ef0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
29f00 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d _LIMIT_VDBE_OP]]
29f10 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
29f20 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e MIT_VDBE_OP</dt>
29f30 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
29f40 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e mum number of in
29f50 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 structions in a
29f60 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
29f70 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 program.** used
29f80 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 to implement an
29f90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 SQL statement.
29fa0 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 If [sqlite3_prep
29fb0 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 are_v2()] or.**
29fc0 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 74 the equivalent t
29fd0 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 65 ries to allocate
29fe0 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 20 space for more
29ff0 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 6f than this many o
2a000 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 73 pcodes.** in a s
2a010 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20 73 ingle prepared s
2a020 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 4c tatement, an SQL
2a030 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 ITE_NOMEM error
2a040 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 is returned.</dd
2a050 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
2a060 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f TE_LIMIT_FUNCTIO
2a070 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 N_ARG]] ^(<dt>SQ
2a080 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
2a090 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 ION_ARG</dt>.**
2a0a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
2a0b0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 number of argume
2a0c0 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f nts on a functio
2a0d0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 n.</dd>)^.**.**
2a0e0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 [[SQLITE_LIMIT_A
2a0f0 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e TTACHED]] ^(<dt>
2a100 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 SQLITE_LIMIT_ATT
2a110 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ACHED</dt>.** <d
2a120 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
2a130 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 mber of [ATTACH
2a140 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 | attached datab
2a150 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a ases].)^</dd>.**
2a160 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
2a170 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f IT_LIKE_PATTERN_
2a180 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 LENGTH]].** ^(<d
2a190 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c t>SQLITE_LIMIT_L
2a1a0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
2a1b0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
2a1c0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
2a1d0 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e h of the pattern
2a1e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
2a1f0 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 [LIKE] or.** [G
2a200 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c LOB] operators.<
2a210 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
2a220 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
2a230 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a ABLE_NUMBER]].**
2a240 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
2a250 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
2a260 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e BER</dt>.** <dd>
2a270 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 The maximum inde
2a280 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 x number of any
2a290 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 [parameter] in a
2a2a0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e n SQL statement.
2a2b0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
2a2c0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f E_LIMIT_TRIGGER_
2a2d0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 DEPTH]] ^(<dt>SQ
2a2e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
2a2f0 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a ER_DEPTH</dt>.**
2a300 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
2a310 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 depth of recurs
2a320 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 ion for triggers
2a330 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
2a340 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f [SQLITE_LIMIT_WO
2a350 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e RKER_THREADS]] ^
2a360 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
2a370 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 T_WORKER_THREADS
2a380 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
2a390 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
2a3a0 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 of auxiliary wor
2a3b0 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74 ker threads that
2a3c0 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 a single.** [pr
2a3d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2a3e0 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 ] may start.</dd
2a3f0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a >)^.** </dl>.*/.
2a400 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
2a410 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 IMIT_LENGTH
2a420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
2a430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2a440 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 LIMIT_SQL_LENGTH
2a450 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2a460 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
2a470 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 _LIMIT_COLUMN
2a480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2a490 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
2a4a0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 E_LIMIT_EXPR_DEP
2a4b0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
2a4c0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
2a4d0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
2a4e0 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 D_SELECT
2a4f0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
2a500 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f ITE_LIMIT_VDBE_O
2a510 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 P
2a520 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 5.#define SQ
2a530 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
2a540 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 ION_ARG
2a550 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 6.#define S
2a560 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 QLITE_LIMIT_ATTA
2a570 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 CHED
2a580 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 7.#define
2a590 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b SQLITE_LIMIT_LIK
2a5a0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 E_PATTERN_LENGTH
2a5b0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 8.#define
2a5c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 SQLITE_LIMIT_VA
2a5d0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 RIABLE_NUMBER
2a5e0 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 9.#defin
2a5f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 e SQLITE_LIMIT_T
2a600 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 RIGGER_DEPTH
2a610 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 10.#defi
2a620 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
2a630 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 WORKER_THREADS
2a640 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 11../*.
2a650 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 ** CAPI3REF: Pre
2a660 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a pare Flags.**.**
2a670 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
2a680 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 define various
2a690 66 6c 61 67 73 20 74 68 61 74 20 63 61 6e 20 62 flags that can b
2a6a0 65 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a e passed into.**
2a6b0 20 22 70 72 65 70 46 6c 61 67 73 22 20 70 61 72 "prepFlags" par
2a6c0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 5b 73 ameter of the [s
2a6d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2a6e0 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 3()] and.** [sql
2a6f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
2a700 33 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2e 3()] interfaces.
2a710 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61 67 73 .**.** New flags
2a720 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
2a730 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
2a740 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
2a750 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 * <dl>.** [[SQLI
2a760 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 TE_PREPARE_PERSI
2a770 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 STENT]] ^(<dt>SQ
2a780 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 LITE_PREPARE_PER
2a790 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 SISTENT</dt>.**
2a7a0 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50 <dd>The SQLITE_P
2a7b0 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e REPARE_PERSISTEN
2a7c0 54 20 66 6c 61 67 20 69 73 20 61 20 68 69 6e 74 T flag is a hint
2a7d0 20 74 6f 20 74 68 65 20 71 75 65 72 79 20 70 6c to the query pl
2a7e0 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 anner.** that th
2a7f0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
2a800 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 72 65 74 ment will be ret
2a810 61 69 6e 65 64 20 66 6f 72 20 61 20 6c 6f 6e 67 ained for a long
2a820 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20 70 72 6f time and.** pro
2a830 62 61 62 6c 79 20 72 65 75 73 65 64 20 6d 61 6e bably reused man
2a840 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57 69 74 68 y times.)^ ^With
2a850 6f 75 74 20 74 68 69 73 20 66 6c 61 67 2c 20 5b out this flag, [
2a860 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2a870 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 v3()].** and [sq
2a880 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2a890 76 33 28 29 5d 20 61 73 73 75 6d 65 20 74 68 61 v3()] assume tha
2a8a0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 t the prepared s
2a8b0 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a tatement will .*
2a8c0 2a 20 62 65 20 75 73 65 64 20 6a 75 73 74 20 6f * be used just o
2a8d0 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73 74 20 61 nce or at most a
2a8e0 20 66 65 77 20 74 69 6d 65 73 20 61 6e 64 20 74 few times and t
2a8f0 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73 hen destroyed us
2a900 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
2a910 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c 61 finalize()] rela
2a920 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20 54 68 65 tively soon. The
2a930 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 current impleme
2a940 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a 2a 2a 20 ntation acts.**
2a950 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 62 79 20 on this hint by
2a960 61 76 6f 69 64 69 6e 67 20 74 68 65 20 75 73 65 avoiding the use
2a970 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d of [lookaside m
2a980 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20 6e 6f 74 emory] so as not
2a990 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74 65 20 74 to.** deplete t
2a9a0 68 65 20 6c 69 6d 69 74 65 64 20 73 74 6f 72 65 he limited store
2a9b0 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 of lookaside me
2a9c0 6d 6f 72 79 2e 20 46 75 74 75 72 65 20 76 65 72 mory. Future ver
2a9d0 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51 4c 69 sions of.** SQLi
2a9e0 74 65 20 6d 61 79 20 61 63 74 20 6f 6e 20 74 68 te may act on th
2a9f0 69 73 20 68 69 6e 74 20 64 69 66 66 65 72 65 6e is hint differen
2aa00 74 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f tly..** </dl>.*/
2aa10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2aa20 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 PREPARE_PERSISTE
2aa30 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 NT
2aa40 30 78 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 0x01../*.** CAPI
2aa50 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 3REF: Compiling
2aa60 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
2aa70 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 .** KEYWORDS: {S
2aa80 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d QL statement com
2aa90 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 piler}.** METHOD
2aaa0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e : sqlite3.** CON
2aab0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 STRUCTOR: sqlite
2aac0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 3_stmt.**.** To
2aad0 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 73 execute an SQL s
2aae0 74 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73 tatement, it mus
2aaf0 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 t first be compi
2ab00 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d led into a byte-
2ab10 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 code.** program
2ab20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 using one of the
2ab30 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72 se routines. Or
2ab40 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 , in other words
2ab50 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 , these routines
2ab60 0a 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 63 .** are construc
2ab70 74 6f 72 73 20 66 6f 72 20 74 68 65 20 5b 70 72 tors for the [pr
2ab80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2ab90 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 ] object..**.**
2aba0 54 68 65 20 70 72 65 66 65 72 72 65 64 20 72 6f The preferred ro
2abb0 75 74 69 6e 65 20 74 6f 20 75 73 65 20 69 73 20 utine to use is
2abc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2abd0 5f 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 _v2()]. The.**
2abe0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2abf0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 ()] interface is
2ac00 20 6c 65 67 61 63 79 20 61 6e 64 20 73 68 6f 75 legacy and shou
2ac10 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a ld be avoided..*
2ac20 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
2ac30 72 65 5f 76 33 28 29 5d 20 68 61 73 20 61 6e 20 re_v3()] has an
2ac40 65 78 74 72 61 20 22 70 72 65 70 46 6c 61 67 73 extra "prepFlags
2ac50 22 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 73 " option that is
2ac60 20 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65 used.** for spe
2ac70 63 69 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a cial purposes..*
2ac80 2a 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 20 *.** The use of
2ac90 74 68 65 20 55 54 46 2d 38 20 69 6e 74 65 72 66 the UTF-8 interf
2aca0 61 63 65 73 20 69 73 20 70 72 65 66 65 72 72 65 aces is preferre
2acb0 64 2c 20 61 73 20 53 51 4c 69 74 65 20 63 75 72 d, as SQLite cur
2acc0 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 rently.** does a
2acd0 6c 6c 20 70 61 72 73 69 6e 67 20 75 73 69 6e 67 ll parsing using
2ace0 20 55 54 46 2d 38 2e 20 20 54 68 65 20 55 54 46 UTF-8. The UTF
2acf0 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 61 -16 interfaces a
2ad00 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61 re provided.** a
2ad10 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e s a convenience.
2ad20 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 The UTF-16 int
2ad30 65 72 66 61 63 65 73 20 77 6f 72 6b 20 62 79 20 erfaces work by
2ad40 63 6f 6e 76 65 72 74 69 6e 67 20 74 68 65 0a 2a converting the.*
2ad50 2a 20 69 6e 70 75 74 20 74 65 78 74 20 69 6e 74 * input text int
2ad60 6f 20 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e o UTF-8, then in
2ad70 76 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 65 voking the corre
2ad80 73 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 69 sponding UTF-8 i
2ad90 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
2ada0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
2adb0 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b nt, "db", is a [
2adc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2add0 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 ion] obtained fr
2ade0 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 om a.** prior su
2adf0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
2ae00 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
2ae10 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
2ae20 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 _v2()] or.** [sq
2ae30 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e lite3_open16()].
2ae40 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 The database c
2ae50 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e onnection must n
2ae60 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f ot have been clo
2ae70 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 sed..**.** The s
2ae80 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 econd argument,
2ae90 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 "zSql", is the s
2aea0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 tatement to be c
2aeb0 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 ompiled, encoded
2aec0 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 .** as either UT
2aed0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 F-8 or UTF-16.
2aee0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 The sqlite3_prep
2aef0 61 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 are(), sqlite3_p
2af00 72 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 repare_v2(),.**
2af10 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 and sqlite3_prep
2af20 61 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65 are_v3().** inte
2af30 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 rfaces use UTF-8
2af40 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 , and sqlite3_pr
2af50 65 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69 74 epare16(), sqlit
2af60 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
2af70 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 ),.** and sqlite
2af80 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 3_prepare16_v3()
2af90 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a use UTF-16..**.
2afa0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 ** ^If the nByte
2afb0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 argument is neg
2afc0 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c ative, then zSql
2afd0 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 is read up to t
2afe0 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f he.** first zero
2aff0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 terminator. ^If
2b000 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 nByte is positi
2b010 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 ve, then it is t
2b020 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
2b030 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 bytes read from
2b040 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 zSql. ^If nByte
2b050 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e is zero, then n
2b060 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 o prepared.** st
2b070 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 atement is gener
2b080 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 ated..** If the
2b090 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 caller knows tha
2b0a0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 t the supplied s
2b0b0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 tring is nul-ter
2b0c0 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a minated, then.**
2b0d0 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c there is a smal
2b0e0 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 l performance ad
2b0f0 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 vantage to passi
2b100 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 ng an nByte para
2b110 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 meter that.** is
2b120 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2b130 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 ytes in the inpu
2b140 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c t string <i>incl
2b150 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 uding</i>.** the
2b160 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e nul-terminator.
2b170 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 .**.** ^If pzTai
2b180 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 l is not NULL th
2b190 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 en *pzTail is ma
2b1a0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 de to point to t
2b1b0 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a he first byte.**
2b1c0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 past the end of
2b1d0 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 the first SQL s
2b1e0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c tatement in zSql
2b1f0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 . These routine
2b200 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c s only.** compil
2b210 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 e the first stat
2b220 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 ement in zSql, s
2b230 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 o *pzTail is lef
2b240 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a t pointing to.**
2b250 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e what remains un
2b260 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 compiled..**.**
2b270 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 ^*ppStmt is left
2b280 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 pointing to a c
2b290 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 ompiled [prepare
2b2a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
2b2b0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 t can be.** exec
2b2c0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 uted using [sqli
2b2d0 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 te3_step()]. ^I
2b2e0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 f there is an er
2b2f0 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 ror, *ppStmt is
2b300 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 set.** to NULL.
2b310 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 ^If the input t
2b320 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 ext contains no
2b330 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 SQL (if the inpu
2b340 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a t is an empty.**
2b350 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d string or a com
2b360 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 ment) then *ppSt
2b370 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c mt is set to NUL
2b380 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e L..** The callin
2b390 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 g procedure is r
2b3a0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 esponsible for d
2b3b0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 eleting the comp
2b3c0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 iled.** SQL stat
2b3d0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c ement using [sql
2b3e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
2b3f0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 after it has fi
2b400 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a nished with it..
2b410 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f ** ppStmt may no
2b420 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a t be NULL..**.**
2b430 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 ^On success, th
2b440 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 e sqlite3_prepar
2b450 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f e() family of ro
2b460 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 utines return [S
2b470 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 QLITE_OK];.** ot
2b480 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f herwise an [erro
2b490 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
2b4a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ned..**.** The s
2b4b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2b4c0 32 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 2(), sqlite3_pre
2b4d0 70 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 74 pare_v3(), sqlit
2b4e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
2b4f0 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 ),.** and sqlite
2b500 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 3_prepare16_v3()
2b510 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
2b520 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
2b530 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 all new programs
2b540 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 69 ..** The older i
2b550 6e 74 65 72 66 61 63 65 73 20 28 73 71 6c 69 74 nterfaces (sqlit
2b560 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 e3_prepare() and
2b570 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
2b580 31 36 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 74 16()).** are ret
2b590 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 ained for backwa
2b5a0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
2b5b0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 y, but their use
2b5c0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e is discouraged.
2b5d0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 22 .** ^In the "vX"
2b5e0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 interfaces, the
2b5f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2b600 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 ent.** that is r
2b610 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 eturned (the [sq
2b620 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 lite3_stmt] obje
2b630 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 ct) contains a c
2b640 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 opy of the.** or
2b650 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e iginal SQL text.
2b660 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 This causes the
2b670 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2b680 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a ] interface to.*
2b690 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 * behave differe
2b6a0 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 ntly in three wa
2b6b0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a ys:.**.** <ol>.*
2b6c0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 * <li>.** ^If th
2b6d0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
2b6e0 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 a changes, inste
2b6f0 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 ad of returning
2b700 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 [SQLITE_SCHEMA]
2b710 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 as it.** always
2b720 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c used to do, [sql
2b730 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c ite3_step()] wil
2b740 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 l automatically
2b750 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 recompile the SQ
2b760 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 L.** statement a
2b770 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 nd try to run it
2b780 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 again. As many
2b790 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 as [SQLITE_MAX_S
2b7a0 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 CHEMA_RETRY].**
2b7b0 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 retries will occ
2b7c0 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 ur before sqlite
2b7d0 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75 3_step() gives u
2b7e0 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e p and returns an
2b7f0 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e error..** </li>
2b800 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e .**.** <li>.** ^
2b810 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 When an error oc
2b820 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 curs, [sqlite3_s
2b830 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 tep()] will retu
2b840 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 rn one of the de
2b850 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 tailed.** [error
2b860 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 codes] or [exte
2b870 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 nded error codes
2b880 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 ]. ^The legacy
2b890 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 behavior was tha
2b8a0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 t.** [sqlite3_st
2b8b0 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 ep()] would only
2b8c0 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 return a generi
2b8d0 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d c [SQLITE_ERROR]
2b8e0 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 result code.**
2b8f0 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 and the applicat
2b900 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 ion would have t
2b910 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 o make a second
2b920 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2b930 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 _reset()].** in
2b940 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 order to find th
2b950 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 e underlying cau
2b960 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 se of the proble
2b970 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 m. With the "v2"
2b980 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 prepare.** inte
2b990 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 rfaces, the unde
2b9a0 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f rlying reason fo
2b9b0 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 r the error is r
2b9c0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 eturned immediat
2b9d0 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a ely..** </li>.**
2b9e0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 .** <li>.** ^If
2b9f0 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c the specific val
2ba00 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 ue bound to [par
2ba10 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 ameter | host pa
2ba20 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 rameter] in the
2ba30 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 .** WHERE clause
2ba40 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 might influence
2ba50 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 the choice of q
2ba60 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 uery plan for a
2ba70 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 statement,.** th
2ba80 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 en the statement
2ba90 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 will be automat
2baa0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 ically recompile
2bab0 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 d, as if there h
2bac0 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 ad been .** a sc
2bad0 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 hema change, on
2bae0 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 the first [sqli
2baf0 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c te3_step()] call
2bb00 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 following any c
2bb10 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 hange.** to the
2bb20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 [sqlite3_bind_te
2bb30 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f xt | bindings] o
2bb40 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 f that [paramete
2bb50 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 r]. .** ^The spe
2bb60 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 cific value of W
2bb70 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 HERE-clause [par
2bb80 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e ameter] might in
2bb90 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 fluence the .**
2bba0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 choice of query
2bbb0 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 plan if the para
2bbc0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 meter is the lef
2bbd0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 t-hand side of a
2bbe0 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 [LIKE].** or [G
2bbf0 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 LOB] operator or
2bc00 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
2bc10 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f r is compared to
2bc20 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 an indexed colu
2bc30 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 mn.** and the [S
2bc40 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 QLITE_ENABLE_STA
2bc50 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 T3] compile-time
2bc60 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c option is enabl
2bc70 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 ed..** </li>.**
2bc80 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e </ol>.**.** <p>^
2bc90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2bca0 76 33 28 29 20 64 69 66 66 65 72 73 20 66 72 6f v3() differs fro
2bcb0 6d 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 m sqlite3_prepar
2bcc0 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68 e_v2() only in h
2bcd0 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74 aving.** the ext
2bce0 72 61 20 70 72 65 70 46 6c 61 67 73 20 70 61 72 ra prepFlags par
2bcf0 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 69 73 ameter, which is
2bd00 20 61 20 62 69 74 20 61 72 72 61 79 20 63 6f 6e a bit array con
2bd10 73 69 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20 sisting of zero
2bd20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 or.** more of th
2bd30 65 20 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 e [SQLITE_PREPAR
2bd40 45 5f 50 45 52 53 49 53 54 45 4e 54 7c 53 51 4c E_PERSISTENT|SQL
2bd50 49 54 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66 ITE_PREPARE_*] f
2bd60 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 lags. ^The.** s
2bd70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2bd80 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 2() interface wo
2bd90 72 6b 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 rks exactly the
2bda0 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 same as.** sqlit
2bdb0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20 e3_prepare_v3()
2bdc0 77 69 74 68 20 61 20 7a 65 72 6f 20 70 72 65 70 with a zero prep
2bdd0 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2e Flags parameter.
2bde0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2bdf0 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 prepare(. sqlit
2be00 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
2be10 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
2be20 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
2be30 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 char *zSql,
2be40 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
2be50 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 ent, UTF-8 encod
2be60 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
2be70 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
2be80 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
2be90 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
2bea0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
2beb0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
2bec0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
2bed0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
2bee0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 onst char **pzTa
2bef0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
2bf00 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
2bf10 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
2bf20 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
2bf30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 e3_prepare_v2(.
2bf40 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
2bf50 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
2bf60 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
2bf70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
2bf80 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
2bf90 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 statement, UTF-8
2bfa0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
2bfb0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
2bfc0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
2bfd0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
2bfe0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
2bff0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
2c000 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
2c010 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
2c020 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
2c030 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
2c040 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
2c050 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
2c060 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 f zSql */.);.int
2c070 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
2c080 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v3(. sqlite3 *
2c090 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
2c0a0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
2c0b0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
2c0c0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
2c0d0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
2c0e0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
2c0f0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
2c100 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
2c110 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
2c120 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
2c130 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e */. unsigned in
2c140 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 t prepFlags, /*
2c150 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c Zero or more SQL
2c160 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 ITE_PREPARE_ fla
2c170 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f gs */. sqlite3_
2c180 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
2c190 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
2c1a0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
2c1b0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 nst char **pzTai
2c1c0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
2c1d0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
2c1e0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
2c1f0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 */.);.int sqlite
2c200 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 3_prepare16(. s
2c210 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
2c220 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
2c230 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
2c240 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c onst void *zSql,
2c250 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
2c260 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 atement, UTF-16
2c270 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
2c280 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
2c290 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
2c2a0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
2c2b0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 n bytes. */. sq
2c2c0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
2c2d0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
2c2e0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
2c2f0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
2c300 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
2c310 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
2c320 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
2c330 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 zSql */.);.int
2c340 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2c350 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 6_v2(. sqlite3
2c360 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
2c370 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
2c380 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
2c390 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 id *zSql,
2c3a0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
2c3b0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 , UTF-16 encoded
2c3c0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
2c3d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2c3e0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
2c3f0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
2c400 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
2c410 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
2c420 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
2c430 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
2c440 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c st void **pzTail
2c450 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
2c460 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
2c470 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
2c480 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 /.);.int sqlite3
2c490 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a 20 _prepare16_v3(.
2c4a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
2c4b0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
2c4c0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
2c4d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 const void *zSq
2c4e0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
2c4f0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 statement, UTF-1
2c500 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6 encoded */. i
2c510 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
2c520 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
2c530 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
2c540 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
2c550 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65 unsigned int pre
2c560 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 pFlags, /* Zero
2c570 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 or more SQLITE_P
2c580 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f REPARE_ flags */
2c590 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
2c5a0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
2c5b0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
2c5c0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
2c5d0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 oid **pzTail
2c5e0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
2c5f0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
2c600 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
2c610 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2c620 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 : Retrieving Sta
2c630 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 tement SQL.** ME
2c640 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2c650 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 mt.**.** ^The sq
2c660 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 lite3_sql(P) int
2c670 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
2c680 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f pointer to a co
2c690 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a py of the UTF-8.
2c6a0 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 ** SQL text used
2c6b0 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 to create [prep
2c6c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2c6d0 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 P if P was.** cr
2c6e0 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 eated by [sqlite
2c6f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 3_prepare_v2()],
2c700 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2c710 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c e_v3()],.** [sql
2c720 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
2c730 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 2()], or [sqlite
2c740 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 3_prepare16_v3()
2c750 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 ]..** ^The sqlit
2c760 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 e3_expanded_sql(
2c770 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 P) interface ret
2c780 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
2c790 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 o a UTF-8.** str
2c7a0 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 ing containing t
2c7b0 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 he SQL text of p
2c7c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2c7d0 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 t P with.** [bou
2c7e0 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 nd parameters] e
2c7f0 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e xpanded..**.** ^
2c800 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 (For example, if
2c810 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 a prepared stat
2c820 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 ement is created
2c830 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a using the SQL.*
2c840 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 * text "SELECT $
2c850 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 abc,:xyz" and if
2c860 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 parameter $abc
2c870 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 is bound to inte
2c880 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 ger 2345.** and
2c890 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 parameter :xyz i
2c8a0 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 s unbound, then
2c8b0 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 sqlite3_sql() wi
2c8c0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 ll return.** the
2c8d0 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 original string
2c8e0 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a , "SELECT $abc,:
2c8f0 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 xyz" but sqlite3
2c900 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a _expanded_sql().
2c910 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 ** will return "
2c920 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c SELECT 2345,NULL
2c930 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ".)^.**.** ^The
2c940 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 sqlite3_expanded
2c950 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 _sql() interface
2c960 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 returns NULL if
2c970 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 insufficient me
2c980 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c mory.** is avail
2c990 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 able to hold the
2c9a0 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 result, or if t
2c9b0 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 he result would
2c9c0 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 exceed the.** th
2c9d0 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 e maximum string
2c9e0 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e length determin
2c9f0 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 ed by the [SQLIT
2ca00 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e E_LIMIT_LENGTH].
2ca10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c .**.** ^The [SQL
2ca20 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c ITE_TRACE_SIZE_L
2ca30 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 IMIT] compile-ti
2ca40 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 me option limits
2ca50 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 the size of.**
2ca60 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 bound parameter
2ca70 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 expansions. ^Th
2ca80 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 e [SQLITE_OMIT_T
2ca90 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 RACE] compile-ti
2caa0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 me.** option cau
2cab0 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 ses sqlite3_expa
2cac0 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c nded_sql() to al
2cad0 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c ways return NULL
2cae0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 ..**.** ^The str
2caf0 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 ing returned by
2cb00 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 sqlite3_sql(P) i
2cb10 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c s managed by SQL
2cb20 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 ite and is.** au
2cb30 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 tomatically free
2cb40 64 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 d when the prepa
2cb50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 red statement is
2cb60 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e finalized..** ^
2cb70 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 The string retur
2cb80 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 ned by sqlite3_e
2cb90 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 xpanded_sql(P),
2cba0 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e on the other han
2cbb0 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 d,.** is obtaine
2cbc0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
2cbd0 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 malloc()] and mu
2cbe0 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68 st be free by th
2cbf0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a e application.**
2cc00 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 by passing it t
2cc10 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
2cc20 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 )]..*/.const cha
2cc30 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 r *sqlite3_sql(s
2cc40 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
2cc50 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 mt);.char *sqlit
2cc60 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 e3_expanded_sql(
2cc70 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
2cc80 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
2cc90 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 I3REF: Determine
2cca0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 If An SQL State
2ccb0 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 ment Writes The
2ccc0 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 Database.** METH
2ccd0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2cce0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2ccf0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c te3_stmt_readonl
2cd00 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 y(X) interface r
2cd10 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e eturns true (non
2cd20 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 -zero) if.** and
2cd30 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 only if the [pr
2cd40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2cd50 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 ] X makes no dir
2cd60 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a ect changes to.*
2cd70 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 * the content of
2cd80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
2cd90 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 le..**.** Note t
2cda0 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e hat [application
2cdb0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
2cdc0 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 ctions] or.** [v
2cdd0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d irtual tables] m
2cde0 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 ight change the
2cdf0 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 database indirec
2ce00 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 tly as a side ef
2ce10 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 fect. .** ^(For
2ce20 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 example, if an
2ce30 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 application defi
2ce40 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 nes a function "
2ce50 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a eval()" that .**
2ce60 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f calls [sqlite3_
2ce70 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 exec()], then th
2ce80 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 e following SQL
2ce90 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a statement would.
2cea0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 ** change the da
2ceb0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f tabase file thro
2cec0 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 ugh side-effects
2ced0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
2cee0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 ote><pre>.**
2cef0 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c SELECT eval('DEL
2cf00 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 ETE FROM t1') FR
2cf10 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e OM t2;.** </pre>
2cf20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
2cf30 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 .** But because
2cf40 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 the [SELECT] sta
2cf50 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 tement does not
2cf60 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 change the datab
2cf70 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 ase file.** dire
2cf80 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 ctly, sqlite3_st
2cf90 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f mt_readonly() wo
2cfa0 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e uld still return
2cfb0 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e true.)^.**.** ^
2cfc0 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 Transaction cont
2cfd0 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 rol statements s
2cfe0 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 uch as [BEGIN],
2cff0 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 [COMMIT], [ROLLB
2d000 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f ACK],.** [SAVEPO
2d010 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 INT], and [RELEA
2d020 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 SE] cause sqlite
2d030 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
2d040 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 ) to return true
2d050 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 ,.** since the s
2d060 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 tatements themse
2d070 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 lves do not actu
2d080 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 ally modify the
2d090 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 database but.**
2d0a0 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 rather they cont
2d0b0 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f rol the timing o
2d0c0 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 f when other sta
2d0d0 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 tements modify t
2d0e0 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e he .** database.
2d0f0 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 ^The [ATTACH]
2d100 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 and [DETACH] sta
2d110 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 tements also cau
2d120 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 se.** sqlite3_st
2d130 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f mt_readonly() to
2d140 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e return true sin
2d150 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 ce, while those
2d160 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 statements.** ch
2d170 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 ange the configu
2d180 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 ration of a data
2d190 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c base connection,
2d1a0 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b they do not mak
2d1b0 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f e .** changes to
2d1c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
2d1d0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
2d1e0 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e es on disk..** ^
2d1f0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 The sqlite3_stmt
2d200 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 _readonly() inte
2d210 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 rface returns tr
2d220 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 ue for [BEGIN] s
2d230 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 ince.** [BEGIN]
2d240 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65 merely sets inte
2d250 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 rnal flags, but
2d260 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e the [BEGIN|BEGIN
2d270 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a IMMEDIATE] and.
2d280 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 ** [BEGIN|BEGIN
2d290 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 EXCLUSIVE] comma
2d2a0 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65 nds do touch the
2d2b0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f database and so
2d2c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 .** sqlite3_stmt
2d2d0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 _readonly() retu
2d2e0 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68 rns false for th
2d2f0 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f ose commands..*/
2d300 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d .int sqlite3_stm
2d310 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 t_readonly(sqlit
2d320 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
2d330 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2d340 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 : Determine If A
2d350 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
2d360 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 ent Has Been Res
2d370 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 et.** METHOD: sq
2d380 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
2d390 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 ^The sqlite3_st
2d3a0 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 mt_busy(S) inter
2d3b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 face returns tru
2d3c0 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 e (non-zero) if
2d3d0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
2d3e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 statement] S ha
2d3f0 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 s been stepped a
2d400 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 t least once usi
2d410 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ng .** [sqlite3_
2d420 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 step(S)] but has
2d430 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 neither run to
2d440 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 completion (retu
2d450 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f rned.** [SQLITE_
2d460 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 DONE] from [sqli
2d470 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f te3_step(S)]) no
2d480 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 r.** been reset
2d490 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 using [sqlite3_r
2d4a0 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 eset(S)]. ^The
2d4b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 sqlite3_stmt_bus
2d4c0 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 y(S).** interfac
2d4d0 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 e returns false
2d4e0 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 if S is a NULL p
2d4f0 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 ointer. If S is
2d500 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 not a .** NULL
2d510 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e pointer and is n
2d520 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ot a pointer to
2d530 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 a valid [prepare
2d540 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
2d550 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 object, then the
2d560 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
2d570 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 efined and proba
2d580 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e bly undesirable.
2d590 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
2d5a0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
2d5b0 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e d in combination
2d5c0 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 [sqlite3_next_s
2d5d0 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 tmt()].** to loc
2d5e0 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 ate all prepared
2d5f0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f statements asso
2d600 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 ciated with a da
2d610 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 tabase .** conne
2d620 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 ction that are i
2d630 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 n need of being
2d640 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e reset. This can
2d650 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 be used,.** for
2d660 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 example, in dia
2d670 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 gnostic routines
2d680 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 to search for p
2d690 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 repared .** stat
2d6a0 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 ements that are
2d6b0 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 holding a transa
2d6c0 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 ction open..*/.i
2d6d0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f nt sqlite3_stmt_
2d6e0 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d busy(sqlite3_stm
2d6f0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
2d700 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 3REF: Dynamicall
2d710 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 y Typed Value Ob
2d720 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ject.** KEYWORDS
2d730 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c : {protected sql
2d740 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 ite3_value} {unp
2d750 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2d760 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 _value}.**.** SQ
2d770 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 Lite uses the sq
2d780 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
2d790 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 ct to represent
2d7a0 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 all values.** th
2d7b0 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 at can be stored
2d7c0 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 in a database t
2d7d0 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 able. SQLite use
2d7e0 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 s dynamic typing
2d7f0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 .** for the valu
2d800 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e es it stores. ^
2d810 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e Values stored in
2d820 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
2d830 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 bjects.** can be
2d840 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 integers, float
2d850 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 ing point values
2d860 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 , strings, BLOBs
2d870 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a , or NULL..**.**
2d880 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 An sqlite3_valu
2d890 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 e object may be
2d8a0 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 either "protecte
2d8b0 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 d" or "unprotect
2d8c0 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 ed"..** Some int
2d8d0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 erfaces require
2d8e0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 a protected sqli
2d8f0 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 te3_value. Othe
2d900 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 r interfaces.**
2d910 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 will accept eith
2d920 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f er a protected o
2d930 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 r an unprotected
2d940 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a sqlite3_value..
2d950 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 ** Every interfa
2d960 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 ce that accepts
2d970 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 sqlite3_value ar
2d980 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 guments specifie
2d990 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 s.** whether or
2d9a0 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 not it requires
2d9b0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 a protected sqli
2d9c0 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a te3_value. The.
2d9d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ** [sqlite3_valu
2d9e0 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 e_dup()] interfa
2d9f0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 ce can be used t
2da00 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 o construct a ne
2da10 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 w .** protected
2da20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 sqlite3_value fr
2da30 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 om an unprotecte
2da40 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
2da50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 .**.** The terms
2da60 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 "protected" and
2da70 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 "unprotected" r
2da80 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 efer to whether
2da90 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 or not.** a mute
2daa0 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 x is held. An i
2dab0 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 nternal mutex is
2dac0 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 held for a prot
2dad0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
2dae0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 _value object bu
2daf0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 t no mutex is he
2db00 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 ld for an unprot
2db10 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
2db20 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 _value object.
2db30 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
2db40 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 piled to be sing
2db50 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 le-threaded.** (
2db60 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 with [SQLITE_THR
2db70 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 EADSAFE=0] and w
2db80 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 ith [sqlite3_thr
2db90 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 eadsafe()] retur
2dba0 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 ning 0).** or if
2dbb0 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 SQLite is run i
2dbc0 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 n one of reduced
2dbd0 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a mutex modes .**
2dbe0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
2dbf0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 SINGLETHREAD] or
2dc00 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
2dc10 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 MULTITHREAD].**
2dc20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f then there is no
2dc30 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 distinction bet
2dc40 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 ween protected a
2dc50 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a nd unprotected.*
2dc60 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
2dc70 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 objects and they
2dc80 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 can be used int
2dc90 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 erchangeably. H
2dca0 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d owever,.** for m
2dcb0 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 aximum code port
2dcc0 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 ability it is re
2dcd0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 commended that a
2dce0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
2dcf0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 till make the di
2dd00 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 stinction betwee
2dd10 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 n protected and
2dd20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
2dd30 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
2dd40 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e ects even when n
2dd50 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 ot strictly requ
2dd60 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ired..**.** ^The
2dd70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
2dd80 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 bjects that are
2dd90 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 passed as parame
2dda0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a ters into the.**
2ddb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
2ddc0 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d of [application-
2ddd0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2dde0 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 tions] are prote
2ddf0 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 cted..** ^The sq
2de00 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
2de10 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a ct returned by.*
2de20 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
2de30 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e n_value()] is un
2de40 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e protected..** Un
2de50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2de60 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
2de70 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 may only be used
2de80 20 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a as arguments.**
2de90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
2dea0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73 ult_value()], [s
2deb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 qlite3_bind_valu
2dec0 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 e()], and.** [sq
2ded0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 lite3_value_dup(
2dee0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 )]..** The [sqli
2def0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c te3_value_blob |
2df00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
2df10 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 ype()] family of
2df20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 .** interfaces r
2df30 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 equire protected
2df40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
2df50 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 bjects..*/.typed
2df60 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
2df70 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f 3_value sqlite3_
2df80 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 value;../*.** CA
2df90 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 PI3REF: SQL Func
2dfa0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a tion Context Obj
2dfb0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f ect.**.** The co
2dfc0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 ntext in which a
2dfd0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 n SQL function e
2dfe0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 xecutes is store
2dff0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 d in an.** sqlit
2e000 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 e3_context objec
2e010 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 t. ^A pointer t
2e020 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e o an sqlite3_con
2e030 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 text object.** i
2e040 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 s always first p
2e050 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 arameter to [app
2e060 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
2e070 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e SQL functions].
2e080 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
2e090 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
2e0a0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
2e0b0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 ntation will pas
2e0c0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 s this.** pointe
2e0d0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 r through into c
2e0e0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
2e0f0 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 _result_int | sq
2e100 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c lite3_result()],
2e110 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 .** [sqlite3_agg
2e120 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
2e130 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 ], [sqlite3_user
2e140 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _data()],.** [sq
2e150 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
2e160 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c _handle()], [sql
2e170 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
2e180 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b ()],.** and/or [
2e190 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
2e1a0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 ata()]..*/.typed
2e1b0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
2e1c0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 3_context sqlite
2e1d0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 3_context;../*.*
2e1e0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 * CAPI3REF: Bind
2e1f0 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 ing Values To Pr
2e200 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
2e210 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
2e220 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 host parameter}
2e230 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 {host parameters
2e240 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 } {host paramete
2e250 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f r name}.** KEYWO
2e260 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 RDS: {SQL parame
2e270 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 ter} {SQL parame
2e280 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 ters} {parameter
2e290 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 binding}.** MET
2e2a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
2e2b0 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 t.**.** ^(In the
2e2c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
2e2d0 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 ext input to [sq
2e2e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2e2f0 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 ()] and its vari
2e300 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c ants,.** literal
2e310 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 s may be replace
2e320 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 d by a [paramete
2e330 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 r] that matches
2e340 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 one of following
2e350 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a .** templates:.*
2e360 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
2e370 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e > ?.** <li> ?N
2e380 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 NN.** <li> :VVV
2e390 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a .** <li> @VVV.*
2e3a0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 * <li> $VVV.**
2e3b0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 </ul>.**.** In t
2e3c0 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f he templates abo
2e3d0 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e ve, NNN represen
2e3e0 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 ts an integer li
2e3f0 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 teral,.** and VV
2e400 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 V represents an
2e410 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 alphanumeric ide
2e420 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 ntifier.)^ ^The
2e430 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 values of these
2e440 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 .** parameters (
2e450 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 also called "hos
2e460 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 t parameter name
2e470 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d s" or "SQL param
2e480 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 eters").** can b
2e490 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 e set using the
2e4a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
2e4b0 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 routines define
2e4c0 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 d here..**.** ^T
2e4d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2e4e0 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 t to the sqlite3
2e4f0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
2e500 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 es is always.**
2e510 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
2e520 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 [sqlite3_stmt]
2e530 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
2e540 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 from.** [sqlite3
2e550 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
2e560 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a r its variants..
2e570 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e **.** ^The secon
2e580 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
2e590 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 e index of the S
2e5a0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 QL parameter to
2e5b0 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 be set..** ^The
2e5c0 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 leftmost SQL par
2e5d0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e ameter has an in
2e5e0 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e dex of 1. ^When
2e5f0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a the same named.
2e600 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 ** SQL parameter
2e610 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 is used more th
2e620 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 an once, second
2e630 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a and subsequent.*
2e640 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 * occurrences ha
2e650 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 ve the same inde
2e660 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f x as the first o
2e670 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 ccurrence..** ^T
2e680 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d he index for nam
2e690 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 ed parameters ca
2e6a0 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 n be looked up u
2e6b0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
2e6c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2e6d0 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 ter_index()] API
2e6e0 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 if desired. ^T
2e6f0 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 he index.** for
2e700 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 "?NNN" parameter
2e710 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f s is the value o
2e720 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e f NNN..** ^The N
2e730 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 NN value must be
2e740 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 between 1 and t
2e750 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 he [sqlite3_limi
2e760 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 t()].** paramete
2e770 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f r [SQLITE_LIMIT_
2e780 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d VARIABLE_NUMBER]
2e790 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a (default value:
2e7a0 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 999)..**.** ^Th
2e7b0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
2e7c0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f is the value to
2e7d0 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 bind to the par
2e7e0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 ameter..** ^If t
2e7f0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
2e800 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 er to sqlite3_bi
2e810 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c nd_text() or sql
2e820 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 ite3_bind_text16
2e830 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
2e840 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 _bind_blob() is
2e850 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
2e860 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 hen the fourth p
2e870 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 arameter.** is i
2e880 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 gnored and the e
2e890 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 nd result is the
2e8a0 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 same as sqlite3
2e8b0 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a _bind_null()..**
2e8c0 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 .** ^(In those r
2e8d0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 outines that hav
2e8e0 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d e a fourth argum
2e8f0 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 ent, its value i
2e900 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
2e910 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
2e920 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 parameter. To b
2e930 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c e clear: the val
2e940 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d ue is the.** num
2e950 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c ber of <u>bytes<
2e960 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 /u> in the value
2e970 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
2e980 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 of characters.)
2e990 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 ^.** ^If the fou
2e9a0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
2e9b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
2e9c0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f xt() or sqlite3_
2e9d0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a bind_text16().**
2e9e0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
2e9f0 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 en the length of
2ea00 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a the string is.*
2ea10 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
2ea20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 bytes up to the
2ea30 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 first zero termi
2ea40 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 nator..** If the
2ea50 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
2ea60 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e r to sqlite3_bin
2ea70 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 d_blob() is nega
2ea80 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 tive, then.** th
2ea90 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e e behavior is un
2eaa0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 defined..** If a
2eab0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f non-negative fo
2eac0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
2ead0 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 s provided to sq
2eae0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 lite3_bind_text(
2eaf0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
2eb00 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 bind_text16() or
2eb10 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
2eb20 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 xt64() then.** t
2eb30 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 hat parameter mu
2eb40 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f st be the byte o
2eb50 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 ffset.** where t
2eb60 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f he NUL terminato
2eb70 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 r would occur as
2eb80 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e suming the strin
2eb90 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 g were NUL.** te
2eba0 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e rminated. If an
2ebb0 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 y NUL characters
2ebc0 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f occur at byte o
2ebd0 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e ffsets less than
2ebe0 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f .** the value o
2ebf0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
2ec00 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 ameter then the
2ec10 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 resulting string
2ec20 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 value will.** c
2ec30 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 ontain embedded
2ec40 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c NULs. The resul
2ec50 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 t of expressions
2ec60 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e involving strin
2ec70 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 gs.** with embed
2ec80 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 ded NULs is unde
2ec90 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
2eca0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
2ecb0 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 to the BLOB and
2ecc0 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 string binding
2ecd0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 interfaces.** is
2ece0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 a destructor us
2ecf0 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 ed to dispose of
2ed00 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 the BLOB or.**
2ed10 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c string after SQL
2ed20 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 ite has finished
2ed30 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 with it. ^The
2ed40 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 destructor is ca
2ed50 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f lled.** to dispo
2ed60 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f se of the BLOB o
2ed70 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 r string even if
2ed80 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e the call to bin
2ed90 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 d API fails..**
2eda0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 ^If the fifth ar
2edb0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 gument is.** the
2edc0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b special value [
2edd0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 SQLITE_STATIC],
2ede0 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 then SQLite assu
2edf0 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 mes that the.**
2ee00 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 information is i
2ee10 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 n static, unmana
2ee20 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f ged space and do
2ee30 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 es not need to b
2ee40 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 e freed..** ^If
2ee50 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 the fifth argume
2ee60 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 nt has the value
2ee70 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 [SQLITE_TRANSIE
2ee80 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c NT], then.** SQL
2ee90 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 ite makes its ow
2eea0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f n private copy o
2eeb0 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 f the data immed
2eec0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a iately, before.*
2eed0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 * the sqlite3_bi
2eee0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 nd_*() routine r
2eef0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 eturns..**.** ^T
2ef00 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e he sixth argumen
2ef10 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e t to sqlite3_bin
2ef20 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 d_text64() must
2ef30 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 be one of.** [SQ
2ef40 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c LITE_UTF8], [SQL
2ef50 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c ITE_UTF16], [SQL
2ef60 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 ITE_UTF16BE], or
2ef70 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 [SQLITE_UTF16LE
2ef80 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 ].** to specify
2ef90 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 the encoding of
2efa0 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 the text in the
2efb0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e third parameter.
2efc0 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 If.** the sixt
2efd0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 h argument to sq
2efe0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 lite3_bind_text6
2eff0 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 4() is not one o
2f000 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 f the.** allowed
2f010 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 values shown ab
2f020 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 ove, or if the t
2f030 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 ext encoding is
2f040 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f different.** fro
2f050 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 m the encoding s
2f060 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
2f070 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c sixth parameter,
2f080 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
2f090 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e or.** is undefin
2f0a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
2f0b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f qlite3_bind_zero
2f0c0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 blob() routine b
2f0d0 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c inds a BLOB of l
2f0e0 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 ength N that.**
2f0f0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a is filled with z
2f100 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 eroes. ^A zerob
2f110 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 lob uses a fixed
2f120 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 amount of memor
2f130 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e y.** (just an in
2f140 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 teger to hold it
2f150 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 s size) while it
2f160 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 is being proces
2f170 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 sed..** Zeroblob
2f180 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 s are intended t
2f190 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 o serve as place
2f1a0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 holders for BLOB
2f1b0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 s whose.** conte
2f1c0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 nt is later writ
2f1d0 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ten using.** [sq
2f1e0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 lite3_blob_open
2f1f0 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c | incremental BL
2f200 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 OB I/O] routines
2f210 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 ..** ^A negative
2f220 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a value for the z
2f230 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 eroblob results
2f240 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 in a zero-length
2f250 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 BLOB..**.** ^Th
2f260 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 e sqlite3_bind_p
2f270 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c 44 ointer(S,I,P,T,D
2f280 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73 65 73 ) routine causes
2f290 20 74 68 65 20 49 2d 74 68 20 70 61 72 61 6d 65 the I-th parame
2f2a0 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61 ter in.** [prepa
2f2b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
2f2c0 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51 4c 20 to have an SQL
2f2d0 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62 value of NULL, b
2f2e0 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a ut to also be.**
2f2f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
2f300 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50 20 6f the pointer P o
2f310 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20 69 73 f type T. ^D is
2f320 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 either a NULL p
2f330 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20 70 ointer or.** a p
2f340 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74 ointer to a dest
2f350 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 ructor function
2f360 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65 20 77 for P. ^SQLite w
2f370 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a ill invoke the.*
2f380 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 * destructor D w
2f390 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67 ith a single arg
2f3a0 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65 6e 20 ument of P when
2f3b0 69 74 20 69 73 20 66 69 6e 69 73 68 65 64 20 75 it is finished u
2f3c0 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65 20 sing.** P. The
2f3d0 54 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 T parameter shou
2f3e0 6c 64 20 62 65 20 61 20 73 74 61 74 69 63 20 73 ld be a static s
2f3f0 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61 62 6c tring, preferabl
2f400 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c 69 y a string.** li
2f410 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c 69 74 teral. The sqlit
2f420 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 e3_bind_pointer(
2f430 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 72 ) routine is par
2f440 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f 69 t of the.** [poi
2f450 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69 6e 74 nter passing int
2f460 65 72 66 61 63 65 5d 20 61 64 64 65 64 20 66 6f erface] added fo
2f470 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e 30 2e r SQLite 3.20.0.
2f480 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f .**.** ^If any o
2f490 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 f the sqlite3_bi
2f4a0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
2f4b0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 are called with
2f4c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a a NULL pointer.*
2f4d0 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 * for the [prepa
2f4e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
2f4f0 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 r with a prepare
2f500 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 d statement for
2f510 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 which.** [sqlite
2f520 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 3_step()] has be
2f530 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 en called more r
2f540 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 ecently than [sq
2f550 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a lite3_reset()],.
2f560 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c ** then the call
2f570 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
2f580 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 LITE_MISUSE]. I
2f590 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 f any sqlite3_bi
2f5a0 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 nd_().** routine
2f5b0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 is passed a [pr
2f5c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2f5d0 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 ] that has been
2f5e0 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a finalized, the.*
2f5f0 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 * result is unde
2f600 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
2f610 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a ly harmful..**.*
2f620 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 * ^Bindings are
2f630 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 not cleared by t
2f640 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 he [sqlite3_rese
2f650 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a t()] routine..**
2f660 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 ^Unbound parame
2f670 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 ters are interpr
2f680 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a eted as NULL..**
2f690 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2f6a0 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 _bind_* routines
2f6b0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
2f6c0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f OK] on success o
2f6d0 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 r an.** [error c
2f6e0 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 ode] if anything
2f6f0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 goes wrong..**
2f700 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d ^[SQLITE_TOOBIG]
2f710 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e might be return
2f720 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f ed if the size o
2f730 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c f a string or BL
2f740 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 OB.** exceeds li
2f750 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 mits imposed by
2f760 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 [sqlite3_limit](
2f770 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 [SQLITE_LIMIT_LE
2f780 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 NGTH]) or.** [SQ
2f790 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d LITE_MAX_LENGTH]
2f7a0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 ..** ^[SQLITE_RA
2f7b0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 NGE] is returned
2f7c0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
2f7d0 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 r.** index is ou
2f7e0 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 t of range. ^[S
2f7f0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 QLITE_NOMEM] is
2f800 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c returned if mall
2f810 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a oc() fails..**.*
2f820 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
2f830 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2f840 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a ter_count()],.**
2f850 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
2f860 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d arameter_name()]
2f870 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 , and [sqlite3_b
2f880 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
2f890 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 dex()]..*/.int s
2f8a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2f8b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2f8c0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a int, const void*
2f8d0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 , int n, void(*)
2f8e0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 (void*));.int sq
2f8f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 lite3_bind_blob6
2f900 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
2f910 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 int, const void
2f920 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 *, sqlite3_uint6
2f930 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 4,.
2f940 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 void(
2f950 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 *)(void*));.int
2f960 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 sqlite3_bind_dou
2f970 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ble(sqlite3_stmt
2f980 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b *, int, double);
2f990 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
2f9a0 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 d_int(sqlite3_st
2f9b0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a mt*, int, int);.
2f9c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
2f9d0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 _int64(sqlite3_s
2f9e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 tmt*, int, sqlit
2f9f0 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 e3_int64);.int s
2fa00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c qlite3_bind_null
2fa10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2fa20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 int);.int sqlite
2fa30 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 3_bind_text(sqli
2fa40 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f te3_stmt*,int,co
2fa50 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f nst char*,int,vo
2fa60 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 id(*)(void*));.i
2fa70 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2fa80 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 text16(sqlite3_s
2fa90 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
2faa0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 void*, int, voi
2fab0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e d(*)(void*));.in
2fac0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 t sqlite3_bind_t
2fad0 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 ext64(sqlite3_st
2fae0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
2faf0 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 char*, sqlite3_u
2fb00 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 int64,.
2fb10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2fb20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 void(*)(void*),
2fb30 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e unsigned char en
2fb40 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c coding);.int sql
2fb50 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
2fb60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2fb70 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 nt, const sqlite
2fb80 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 3_value*);.int s
2fb90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e qlite3_bind_poin
2fba0 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ter(sqlite3_stmt
2fbb0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 63 *, int, void*, c
2fbc0 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f 69 64 28 onst char*,void(
2fbd0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 *)(void*));.int
2fbe0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 sqlite3_bind_zer
2fbf0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 oblob(sqlite3_st
2fc00 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 mt*, int, int n)
2fc10 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
2fc20 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 nd_zeroblob64(sq
2fc30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2fc40 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 , sqlite3_uint64
2fc50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2fc60 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 EF: Number Of SQ
2fc70 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 L Parameters.**
2fc80 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
2fc90 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 stmt.**.** ^This
2fca0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 routine can be
2fcb0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 used to find the
2fcc0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 number of [SQL
2fcd0 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 parameters].** i
2fce0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
2fcf0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 atement]. SQL p
2fd00 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f arameters are to
2fd10 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 kens of the.** f
2fd20 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c orm "?", "?NNN",
2fd30 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c ":AAA", "$AAA",
2fd40 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 or "@AAA" that
2fd50 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 serve as.** plac
2fd60 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c eholders for val
2fd70 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 ues that are [sq
2fd80 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
2fd90 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 | bound].** to t
2fda0 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 he parameters at
2fdb0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a a later time..*
2fdc0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 *.** ^(This rout
2fdd0 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 ine actually ret
2fde0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f urns the index o
2fdf0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 f the largest (r
2fe00 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 ightmost).** par
2fe10 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 ameter. For all
2fe20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e forms except ?NN
2fe30 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 N, this will cor
2fe40 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a respond to the.*
2fe50 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 * number of uniq
2fe60 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ue parameters.
2fe70 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 If parameters of
2fe80 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 the ?NNN form a
2fe90 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 re used,.** ther
2fea0 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e e may be gaps in
2feb0 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a the list.)^.**.
2fec0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
2fed0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
2fee0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
2fef0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2ff00 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
2ff10 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
2ff20 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2ff30 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
2ff40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
2ff50 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
2ff60 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 t(sqlite3_stmt*)
2ff70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2ff80 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 F: Name Of A Hos
2ff90 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d t Parameter.** M
2ffa0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
2ffb0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 tmt.**.** ^The s
2ffc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2ffd0 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 meter_name(P,N)
2ffe0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2fff0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 s.** the name of
30000 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 the N-th [SQL p
30010 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 arameter] in the
30020 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
30030 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 ment] P..** ^(SQ
30040 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 L parameters of
30050 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 the form "?NNN"
30060 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
30070 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
30080 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 have a name whi
30090 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 ch is the string
300a0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
300b0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
300c0 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 $AAA".** respect
300d0 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 ively..** In oth
300e0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e er words, the in
300f0 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 itial ":" or "$"
30100 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a or "@" or "?".*
30110 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 * is included as
30120 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d part of the nam
30130 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 e.)^.** ^Paramet
30140 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 ers of the form
30150 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f "?" without a fo
30160 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 llowing integer
30170 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 have no name.**
30180 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 and are referred
30190 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 to as "nameless
301a0 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 " or "anonymous
301b0 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a parameters"..**.
301c0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f ** ^The first ho
301d0 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 st parameter has
301e0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 an index of 1,
301f0 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 not 0..**.** ^If
30200 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 the value N is
30210 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 out of range or
30220 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 if the N-th para
30230 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 meter is.** name
30240 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 less, then NULL
30250 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 is returned. ^T
30260 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
30270 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 ng is.** always
30280 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e in UTF-8 encodin
30290 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 g even if the na
302a0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 med parameter wa
302b0 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 s.** originally
302c0 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 specified as UTF
302d0 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f -16 in [sqlite3_
302e0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a prepare16()],.**
302f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
30300 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73 e16_v2()], or [s
30310 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
30320 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 _v3()]..**.** Se
30330 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
30340 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
30350 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
30360 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
30370 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
30380 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
30390 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
303a0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e index()]..*/.con
303b0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
303c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
303d0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
303e0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a t*, int);../*.**
303f0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 CAPI3REF: Index
30400 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 Of A Parameter
30410 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d With A Given Nam
30420 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c e.** METHOD: sql
30430 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
30440 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 ^Return the inde
30450 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 x of an SQL para
30460 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 meter given its
30470 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 name. ^The.** i
30480 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 ndex value retur
30490 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 ned is suitable
304a0 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 for use as the s
304b0 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 econd.** paramet
304c0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 er to [sqlite3_b
304d0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
304e0 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 _bind()]. ^A ze
304f0 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 ro.** is returne
30500 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 d if no matching
30510 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f parameter is fo
30520 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d und. ^The param
30530 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 eter.** name mus
30540 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 t be given in UT
30550 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 F-8 even if the
30560 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 original stateme
30570 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 nt.** was prepar
30580 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 ed from UTF-16 t
30590 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ext using [sqlit
305a0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
305b0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
305c0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 3_prepare16_v3()
305d0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 ]..**.** See als
305e0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
305f0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
30600 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nd()],.** [sqlit
30610 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
30620 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a r_count()], and.
30630 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
30640 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
30650 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 )]..*/.int sqlit
30660 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
30670 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f r_index(sqlite3_
30680 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 stmt*, const cha
30690 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a r *zName);../*.*
306a0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
306b0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f t All Bindings O
306c0 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 n A Prepared Sta
306d0 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 tement.** METHOD
306e0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
306f0 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 *.** ^Contrary t
30700 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 o the intuition
30710 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 of many, [sqlite
30720 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 3_reset()] does
30730 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 not reset.** the
30740 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
30750 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 lob | bindings]
30760 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 on a [prepared s
30770 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 tatement]..** ^U
30780 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 se this routine
30790 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 to reset all hos
307a0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 t parameters to
307b0 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c NULL..*/.int sql
307c0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 ite3_clear_bindi
307d0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ngs(sqlite3_stmt
307e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
307f0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 REF: Number Of C
30800 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 olumns In A Resu
30810 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 lt Set.** METHOD
30820 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
30830 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 *.** ^Return the
30840 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
30850 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ns in the result
30860 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 set returned by
30870 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
30880 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 d statement]. ^I
30890 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 f this routine r
308a0 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d eturns 0, that m
308b0 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72 eans the .** [pr
308c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
308d0 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74 ] returns no dat
308e0 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 a (for example a
308f0 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 n [UPDATE])..**
30900 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62 ^However, just b
30910 65 63 61 75 73 65 20 74 68 69 73 20 72 6f 75 74 ecause this rout
30920 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ine returns a po
30930 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f sitive number do
30940 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 es not.** mean t
30950 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 hat one or more
30960 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c rows of data wil
30970 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 l be returned.
30980 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d ^A SELECT statem
30990 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 ent.** will alwa
309a0 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 74 69 ys have a positi
309b0 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ve sqlite3_colum
309c0 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65 n_count() but de
309d0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a pending on the.*
309e0 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 * WHERE clause c
309f0 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 onstraints and t
30a00 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74 he table content
30a10 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 75 72 , it might retur
30a20 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a n no rows..**.**
30a30 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
30a40 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 te3_data_count()
30a50 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
30a60 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 _column_count(sq
30a70 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
30a80 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
30a90 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 REF: Column Name
30aa0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 s In A Result Se
30ab0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
30ac0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
30ad0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
30ae0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 return the name
30af0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 assigned to a pa
30b00 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a rticular column.
30b10 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ** in the result
30b20 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 set of a [SELEC
30b30 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e T] statement. ^
30b40 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 The sqlite3_colu
30b50 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 mn_name().** int
30b60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
30b70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 pointer to a ze
30b80 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
30b90 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e F-8 string.** an
30ba0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
30bb0 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e _name16() return
30bc0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
30bd0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
30be0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e .** UTF-16 strin
30bf0 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 g. ^The first p
30c00 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
30c10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
30c20 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 ent].** that imp
30c30 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c lements the [SEL
30c40 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 ECT] statement.
30c50 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 ^The second para
30c60 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 meter is the.**
30c70 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 column number.
30c80 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f ^The leftmost co
30c90 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 lumn is number 0
30ca0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 ..**.** ^The ret
30cb0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 urned string poi
30cc0 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e nter is valid un
30cd0 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b til either the [
30ce0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
30cf0 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f nt].** is destro
30d00 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f yed by [sqlite3_
30d10 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 finalize()] or u
30d20 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 ntil the stateme
30d30 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 nt is automatica
30d40 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 lly.** reprepare
30d50 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 d by the first c
30d60 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
30d70 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 step()] for a pa
30d80 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 rticular run.**
30d90 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 or until the nex
30da0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c t call to.** sql
30db0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
30dc0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f () or sqlite3_co
30dd0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e lumn_name16() on
30de0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e the same column
30df0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 ..**.** ^If sqli
30e00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 te3_malloc() fai
30e10 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 ls during the pr
30e20 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 ocessing of eith
30e30 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 er routine.** (f
30e40 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e or example durin
30e50 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 g a conversion f
30e60 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 rom UTF-8 to UTF
30e70 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e -16) then a.** N
30e80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
30e90 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
30ea0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 The name of a re
30eb0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 sult column is t
30ec0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
30ed0 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a "AS" clause for.
30ee0 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 ** that column,
30ef0 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 if there is an A
30f00 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 S clause. If th
30f10 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 ere is no AS cla
30f20 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 use.** then the
30f30 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 name of the colu
30f40 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 mn is unspecifie
30f50 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 d and may change
30f60 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c from.** one rel
30f70 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 ease of SQLite t
30f80 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 o the next..*/.c
30f90 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
30fa0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 e3_column_name(s
30fb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
30fc0 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 t N);.const void
30fd0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
30fe0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
30ff0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a stmt*, int N);..
31000 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
31010 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 Source Of Data I
31020 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 n A Query Result
31030 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
31040 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
31050 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 These routines p
31060 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 rovide a means t
31070 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 o determine the
31080 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c database, table,
31090 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f and.** table co
310a0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 lumn that is the
310b0 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 origin of a par
310c0 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 ticular result c
310d0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c olumn in.** [SEL
310e0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a ECT] statement..
310f0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 ** ^The name of
31100 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 the database or
31110 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 table or column
31120 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 can be returned
31130 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 as.** either a U
31140 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 TF-8 or UTF-16 s
31150 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 tring. ^The _da
31160 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 tabase_ routines
31170 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 return.** the d
31180 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 atabase name, th
31190 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e e _table_ routin
311a0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 es return the ta
311b0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a ble name, and.**
311c0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 the origin_ rou
311d0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 tines return the
311e0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a column name..**
311f0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 ^The returned s
31200 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 tring is valid u
31210 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 ntil the [prepar
31220 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 ed statement] is
31230 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 destroyed.** us
31240 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
31250 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 alize()] or unti
31260 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 l the statement
31270 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 is automatically
31280 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 .** reprepared b
31290 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c y the first call
312a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
312b0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 p()] for a parti
312c0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 cular run.** or
312d0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 until the same i
312e0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 nformation is re
312f0 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e quested.** again
31300 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 in a different
31310 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 encoding..**.**
31320 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 ^The names retur
31330 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 ned are the orig
31340 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 inal un-aliased
31350 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 names of the.**
31360 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c database, table,
31370 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a and column..**.
31380 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
31390 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 gument to these
313a0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 interfaces is a
313b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
313c0 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 ent]..** ^These
313d0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
313e0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
313f0 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c ut the Nth resul
31400 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 t column returne
31410 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 d by.** the stat
31420 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 ement, where N i
31430 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e s the second fun
31440 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a ction argument..
31450 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 ** ^The left-mos
31460 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 t column is colu
31470 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 mn 0 for these r
31480 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e outines..**.** ^
31490 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d If the Nth colum
314a0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 n returned by th
314b0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
314c0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a n expression or.
314d0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 ** subquery and
314e0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 is not a column
314f0 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 value, then all
31500 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f of these functio
31510 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c ns return.** NUL
31520 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 L. ^These routi
31530 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 ne might also re
31540 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d turn NULL if a m
31550 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
31560 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 error.** occurs
31570 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 . ^Otherwise, t
31580 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e hey return the n
31590 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 ame of the attac
315a0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 hed database, ta
315b0 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d ble,.** or colum
315c0 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 n that query res
315d0 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 ult column was e
315e0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a xtracted from..*
315f0 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c *.** ^As with al
31600 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 l other SQLite A
31610 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 PIs, those whose
31620 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 names end with
31630 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 "16" return.** U
31640 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 TF-16 encoded st
31650 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 rings and the ot
31660 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 her functions re
31670 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a turn UTF-8..**.*
31680 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 * ^These APIs ar
31690 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 e only available
316a0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 if the library
316b0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 was compiled wit
316c0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 h the.** [SQLITE
316d0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d _ENABLE_COLUMN_M
316e0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 ETADATA] C-prepr
316f0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a ocessor symbol..
31700 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 **.** If two or
31710 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c more threads cal
31720 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 l one or more of
31730 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
31740 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 against the same
31750 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 .** prepared sta
31760 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d tement and colum
31770 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 n at the same ti
31780 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 me then the resu
31790 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 lts are.** undef
317a0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 ined..**.** If t
317b0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 wo or more threa
317c0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d ds call one or m
317d0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ore.** [sqlite3_
317e0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
317f0 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 name | column me
31800 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 tadata interface
31810 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 s].** for the sa
31820 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 me [prepared sta
31830 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 tement] and resu
31840 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 lt column.** at
31850 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 the same time th
31860 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 en the results a
31870 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f re undefined..*/
31880 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
31890 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 ite3_column_data
318a0 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 base_name(sqlite
318b0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
318c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
318d0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 3_column_databas
318e0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 e_name16(sqlite3
318f0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
31900 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
31910 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 _column_table_na
31920 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
31930 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
31940 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
31950 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 n_table_name16(s
31960 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
31970 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
31980 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 qlite3_column_or
31990 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 igin_name(sqlite
319a0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
319b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
319c0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 3_column_origin_
319d0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
319e0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a tmt*,int);../*.*
319f0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c * CAPI3REF: Decl
31a00 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 ared Datatype Of
31a10 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a A Query Result.
31a20 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
31a30 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 e3_stmt.**.** ^(
31a40 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
31a50 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 ter is a [prepar
31a60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a ed statement]..*
31a70 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d * If this statem
31a80 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 ent is a [SELECT
31a90 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 ] statement and
31aa0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f the Nth column o
31ab0 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 f the.** returne
31ac0 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 d result set of
31ad0 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 that [SELECT] is
31ae0 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 a table column
31af0 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 (not an.** expre
31b00 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 ssion or subquer
31b10 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c y) then the decl
31b20 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 ared type of the
31b30 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e table.** column
31b40 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 is returned.)^
31b50 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c ^If the Nth col
31b60 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c umn of the resul
31b70 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 t set is an.** e
31b80 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 xpression or sub
31b90 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 query, then a NU
31ba0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 LL pointer is re
31bb0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 turned..** ^The
31bc0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
31bd0 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 is always UTF-8
31be0 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e encoded..**.** ^
31bf0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 (For example, gi
31c00 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 ven the database
31c10 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 schema:.**.** C
31c20 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 REATE TABLE t1(c
31c30 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 1 VARIANT);.**.*
31c40 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 * and the follow
31c50 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f ing statement to
31c60 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a be compiled:.**
31c70 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 .** SELECT c1 +
31c80 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 1, c1 FROM t1;.*
31c90 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e *.** this routin
31ca0 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 e would return t
31cb0 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 he string "VARIA
31cc0 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f NT" for the seco
31cd0 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c nd result.** col
31ce0 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 umn (i==1), and
31cf0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 a NULL pointer f
31d00 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 or the first res
31d10 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 ult column (i==0
31d20 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 ).)^.**.** ^SQLi
31d30 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 te uses dynamic
31d40 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e run-time typing.
31d50 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 ^So just becau
31d60 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 se a column.** i
31d70 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f s declared to co
31d80 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c ntain a particul
31d90 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 ar type does not
31da0 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a mean that the.*
31db0 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e * data stored in
31dc0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 that column is
31dd0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 of the declared
31de0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 type. SQLite is
31df0 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 .** strongly typ
31e00 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 ed, but the typi
31e10 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f ng is dynamic no
31e20 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 t static. ^Type
31e30 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 .** is associate
31e40 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 d with individua
31e50 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 l values, not wi
31e60 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 th the container
31e70 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c s.** used to hol
31e80 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a d those values..
31e90 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
31ea0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 qlite3_column_de
31eb0 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 cltype(sqlite3_s
31ec0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 tmt*,int);.const
31ed0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
31ee0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 olumn_decltype16
31ef0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
31f00 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
31f10 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 3REF: Evaluate A
31f20 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a n SQL Statement.
31f30 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
31f40 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 e3_stmt.**.** Af
31f50 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 ter a [prepared
31f60 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 statement] has b
31f70 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 een prepared usi
31f80 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71 ng any of.** [sq
31f90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
31fa0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 ()], [sqlite3_pr
31fb0 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 epare_v3()], [sq
31fc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
31fd0 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 v2()],.** or [sq
31fe0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
31ff0 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 v3()] or one of
32000 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e the legacy.** in
32010 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 terfaces [sqlite
32020 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
32030 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
32040 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 16()], this func
32050 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 tion.** must be
32060 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f called one or mo
32070 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c re times to eval
32080 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 uate the stateme
32090 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 nt..**.** The de
320a0 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 tails of the beh
320b0 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c avior of the sql
320c0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 ite3_step() inte
320d0 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 rface depend.**
320e0 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 on whether the s
320f0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 tatement was pre
32100 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 pared using the
32110 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74 65 72 newer "vX" inter
32120 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 faces.** [sqlite
32130 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 3_prepare_v3()],
32140 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
32150 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 e_v2()], [sqlite
32160 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 3_prepare16_v3()
32170 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 ],.** [sqlite3_p
32180 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f repare16_v2()] o
32190 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 r the older lega
321a0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 cy.** interfaces
321b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
321c0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
321d0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 3_prepare16()].
321e0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a The use of the.
321f0 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74 65 ** new "vX" inte
32200 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 rface is recomme
32210 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 nded for new app
32220 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 lications but th
32230 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 e legacy.** inte
32240 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 rface will conti
32250 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 nue to be suppor
32260 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 ted..**.** ^In t
32270 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
32280 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 ace, the return
32290 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 value will be ei
322a0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 ther [SQLITE_BUS
322b0 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 Y],.** [SQLITE_D
322c0 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f ONE], [SQLITE_RO
322d0 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f W], [SQLITE_ERRO
322e0 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d R], or [SQLITE_M
322f0 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 ISUSE]..** ^With
32300 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
32310 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 ace, any of the
32320 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f other [result co
32330 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 des] or.** [exte
32340 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
32350 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 s] might be retu
32360 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a rned as well..**
32370 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 .** ^[SQLITE_BUS
32380 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 Y] means that th
32390 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e e database engin
323a0 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 e was unable to
323b0 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 acquire the.** d
323c0 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 atabase locks it
323d0 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 needs to do its
323e0 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 job. ^If the s
323f0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 tatement is a [C
32400 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 OMMIT].** or occ
32410 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 urs outside of a
32420 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 n explicit trans
32430 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 action, then you
32440 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a can retry the.*
32450 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 * statement. If
32460 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
32470 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d s not a [COMMIT]
32480 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 and occurs with
32490 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 in an.** explici
324a0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 t transaction th
324b0 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f en you should ro
324c0 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 llback the trans
324d0 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a action before.**
324e0 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a continuing..**.
324f0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 ** ^[SQLITE_DONE
32500 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
32510 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 statement has f
32520 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e inished executin
32530 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c g.** successfull
32540 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 y. sqlite3_step
32550 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 () should not be
32560 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e called again on
32570 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a this virtual.**
32580 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 machine without
32590 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b first calling [
325a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
325b0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 to reset the vi
325c0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 rtual.** machine
325d0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 back to its ini
325e0 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a tial state..**.*
325f0 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 * ^If the SQL st
32600 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 atement being ex
32610 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 ecuted returns a
32620 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 ny data, then [S
32630 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 QLITE_ROW].** is
32640 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 returned each t
32650 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 ime a new row of
32660 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 data is ready f
32670 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 or processing by
32680 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 the.** caller.
32690 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 The values may b
326a0 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 e accessed using
326b0 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 the [column acc
326c0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a ess functions]..
326d0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 ** sqlite3_step(
326e0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 ) is called agai
326f0 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 n to retrieve th
32700 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 e next row of da
32710 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 ta..**.** ^[SQLI
32720 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 TE_ERROR] means
32730 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 that a run-time
32740 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 error (such as a
32750 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 constraint.** v
32760 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 iolation) has oc
32770 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 curred. sqlite3
32780 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e _step() should n
32790 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 ot be called aga
327a0 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e in on.** the VM.
327b0 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f More informatio
327c0 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 n may be found b
327d0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 y calling [sqlit
327e0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a e3_errmsg()]..**
327f0 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 ^With the legac
32800 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d y interface, a m
32810 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 ore specific err
32820 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 or code (for exa
32830 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 mple,.** [SQLITE
32840 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 _INTERRUPT], [SQ
32850 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 LITE_SCHEMA], [S
32860 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 QLITE_CORRUPT],
32870 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a and so forth).**
32880 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 can be obtained
32890 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c by calling [sql
328a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e ite3_reset()] on
328b0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
328c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e d statement]. ^
328d0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 In the "v2" inte
328e0 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f rface,.** the mo
328f0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f re specific erro
32900 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e r code is return
32910 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 ed directly by s
32920 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a qlite3_step()..*
32930 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 *.** [SQLITE_MIS
32940 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 USE] means that
32950 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 the this routine
32960 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 was called inap
32970 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 propriately..**
32980 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 Perhaps it was c
32990 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 alled on a [prep
329a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
329b0 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 that has.** alre
329c0 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 ady been [sqlite
329d0 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 3_finalize | fin
329e0 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e alized] or on on
329f0 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 e that had.** pr
32a00 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 eviously returne
32a10 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d d [SQLITE_ERROR]
32a20 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 or [SQLITE_DONE
32a30 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a ]. Or it could.
32a40 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 ** be the case t
32a50 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 hat the same dat
32a60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
32a70 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 is being used b
32a80 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 y two or.** more
32a90 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 threads at the
32aa0 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 same moment in t
32ab0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 ime..**.** For a
32ac0 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 ll versions of S
32ad0 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 QLite up to and
32ae0 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 including 3.6.23
32af0 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a .1, a call to.**
32b00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
32b10 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 )] was required
32b20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 after sqlite3_st
32b30 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e ep() returned an
32b40 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 ything.** other
32b50 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 than [SQLITE_ROW
32b60 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 ] before any sub
32b70 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 sequent invocati
32b80 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 on of.** sqlite3
32b90 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 _step(). Failur
32ba0 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 e to reset the p
32bb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
32bc0 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c t using .** [sql
32bd0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f ite3_reset()] wo
32be0 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e uld result in an
32bf0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
32c00 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 return from.**
32c10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 sqlite3_step().
32c20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72 73 But after [vers
32c30 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b ion 3.6.23.1] ([
32c40 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d dateof:3.6.23.1]
32c50 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 ,.** sqlite3_ste
32c60 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c p() began.** cal
32c70 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 ling [sqlite3_re
32c80 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 set()] automatic
32c90 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 ally in this cir
32ca0 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 cumstance rather
32cb0 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 .** than returni
32cc0 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 ng [SQLITE_MISUS
32cd0 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 E]. This is not
32ce0 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f considered a co
32cf0 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 mpatibility.** b
32d00 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 reak because any
32d10 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 application tha
32d20 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20 t ever receives
32d30 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 an SQLITE_MISUSE
32d40 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f error.** is bro
32d50 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f ken by definitio
32d60 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f n. The [SQLITE_
32d70 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 OMIT_AUTORESET]
32d80 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
32d90 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 ion.** can be us
32da0 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 ed to restore th
32db0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f e legacy behavio
32dc0 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 r..**.** <b>Goof
32dd0 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 y Interface Aler
32de0 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 t:</b> In the le
32df0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 gacy interface,
32e00 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 the sqlite3_step
32e10 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 ().** API always
32e20 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 returns a gener
32e30 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b ic error code, [
32e40 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 SQLITE_ERROR], f
32e50 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 ollowing any.**
32e60 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e error other than
32e70 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 [SQLITE_BUSY] a
32e80 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 nd [SQLITE_MISUS
32e90 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 E]. You must ca
32ea0 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 ll.** [sqlite3_r
32eb0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 eset()] or [sqli
32ec0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
32ed0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 in order to find
32ee0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 one of the.** s
32ef0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 pecific [error c
32f00 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 odes] that bette
32f10 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 r describes the
32f20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d error..** We adm
32f30 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 it that this is
32f40 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 a goofy design.
32f50 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 The problem has
32f60 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 been fixed.** w
32f70 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 ith the "v2" int
32f80 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 erface. If you
32f90 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 prepare all of y
32fa0 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e our SQL statemen
32fb0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c ts.** using [sql
32fc0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 ite3_prepare_v3(
32fd0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
32fe0 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 repare_v2()].**
32ff0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
33000 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 5b are16_v2()] or [
33010 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
33020 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64 0a 6_v3()] instead.
33030 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 ** of the legacy
33040 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
33050 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
33060 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 3_prepare16()] i
33070 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 nterfaces,.** th
33080 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 en the more spec
33090 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 ific [error code
330a0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 s] are returned
330b0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 directly.** by s
330c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
330d0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 The use of the "
330e0 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 20 69 vX" interfaces i
330f0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a s recommended..*
33100 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 /.int sqlite3_st
33110 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ep(sqlite3_stmt*
33120 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
33130 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f EF: Number of co
33140 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c lumns in a resul
33150 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a t set.** METHOD:
33160 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
33170 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
33180 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 _data_count(P) i
33190 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
331a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
331b0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a olumns in the.**
331c0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 current row of
331d0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f the result set o
331e0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 f [prepared stat
331f0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 ement] P..** ^If
33200 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
33210 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 ent P does not h
33220 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 ave results read
33230 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 y to return.** (
33240 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 via calls to the
33250 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
33260 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 _int | sqlite3_c
33270 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a olumn_*()] of.**
33280 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 interfaces) the
33290 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 n sqlite3_data_c
332a0 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 ount(P) returns
332b0 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 0..** ^The sqlit
332c0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 e3_data_count(P)
332d0 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 routine also re
332e0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 turns 0 if P is
332f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
33300 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
33310 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f data_count(P) ro
33320 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 utine returns 0
33330 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 if the previous
33340 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
33350 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 te3_step](P) ret
33360 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f urned [SQLITE_DO
33370 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 NE]. ^The sqlit
33380 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 e3_data_count(P)
33390 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 .** will return
333a0 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 non-zero if prev
333b0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 ious call to [sq
333c0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 lite3_step](P) r
333d0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 eturned.** [SQLI
333e0 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 TE_ROW], except
333f0 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 in the case of t
33400 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 he [PRAGMA incre
33410 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a mental_vacuum].*
33420 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 * where it alway
33430 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 s returns zero s
33440 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f ince each step o
33450 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 f that multi-ste
33460 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 p.** pragma retu
33470 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 rns 0 columns of
33480 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 data..**.** See
33490 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
334a0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a column_count()].
334b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 */.int sqlite3_d
334c0 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 ata_count(sqlite
334d0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
334e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
334f0 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 Fundamental Dat
33500 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 atypes.** KEYWOR
33510 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a DS: SQLITE_TEXT.
33520 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 **.** ^(Every va
33530 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 lue in SQLite ha
33540 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 s one of five fu
33550 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 ndamental dataty
33560 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a pes:.**.** <ul>.
33570 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 ** <li> 64-bit s
33580 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a igned integer.**
33590 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 <li> 64-bit IEE
335a0 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 E floating point
335b0 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 number.** <li>
335c0 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 string.** <li> B
335d0 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c LOB.** <li> NULL
335e0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a .** </ul>)^.**.*
335f0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
33600 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 s are codes for
33610 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 each of those ty
33620 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 pes..**.** Note
33630 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f that the SQLITE_
33640 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 TEXT constant wa
33650 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 s also used in S
33660 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a QLite version 2.
33670 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 ** for a complet
33680 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 ely different me
33690 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 aning. Software
336a0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 that links agai
336b0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 nst both.** SQLi
336c0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 te version 2 and
336d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
336e0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 3 should use SQL
336f0 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a ITE3_TEXT, not.*
33700 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a * SQLITE_TEXT..*
33710 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
33720 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 _INTEGER 1.#def
33730 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 ine SQLITE_FLOAT
33740 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
33750 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a LITE_BLOB 4.
33760 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
33770 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 ULL 5.#ifdef
33780 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 SQLITE_TEXT.# u
33790 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 ndef SQLITE_TEXT
337a0 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 .#else.# define
337b0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 SQLITE_TEXT
337c0 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 3.#endif.#define
337d0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 SQLITE3_TEXT
337e0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 3../*.** CAPI3
337f0 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 REF: Result Valu
33800 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a es From A Query.
33810 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f ** KEYWORDS: {co
33820 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 lumn access func
33830 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 tions}.** METHOD
33840 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
33850 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a *.** <b>Summary:
33860 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 </b>.** <blockqu
33870 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65 ote><table borde
33880 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d r=0 cellpadding=
33890 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e 0 cellspacing=0>
338a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 .** <tr><td><b>s
338b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
338c0 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b ob</b><td>→
338d0 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74 0a <td>BLOB result.
338e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 ** <tr><td><b>sq
338f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 lite3_column_dou
33900 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 ble</b><td>&rarr
33910 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75 6c 74 ;<td>REAL result
33920 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 .** <tr><td><b>s
33930 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e qlite3_column_in
33940 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c t</b><td>→<
33950 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45 47 45 td>32-bit INTEGE
33960 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e R result.** <tr>
33970 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 <td><b>sqlite3_c
33980 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c olumn_int64</b><
33990 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34 2d td>→<td>64-
339a0 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73 75 bit INTEGER resu
339b0 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 lt.** <tr><td><b
339c0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
339d0 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 text</b><td>&rar
339e0 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45 58 54 r;<td>UTF-8 TEXT
339f0 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c result.** <tr><
33a00 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f td><b>sqlite3_co
33a10 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e 3c lumn_text16</b><
33a20 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 td>→<td>UTF
33a30 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c 74 0a -16 TEXT result.
33a40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 ** <tr><td><b>sq
33a50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
33a60 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b ue</b><td>→
33a70 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74 20 61 <td>The result a
33a80 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 s an .** [sqlite
33a90 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65 63 3_value|unprotec
33aa0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
33ab0 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74 e] object..** <t
33ac0 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e r><td> <td>
33ad0 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b <td>
33ae0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 .** <tr><td><b>s
33af0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
33b00 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 tes</b><td>&rarr
33b10 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61 20 42 ;<td>Size of a B
33b20 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46 2d LOB.** or a UTF-
33b30 38 20 54 45 58 54 20 72 65 73 75 6c 74 20 69 6e 8 TEXT result in
33b40 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 bytes.** <tr><t
33b50 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c d><b>sqlite3_col
33b60 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62 73 70 umn_bytes16 
33b70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c ; </b>.** <
33b80 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b 26 td>→ &
33b90 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 nbsp;<td>Size of
33ba0 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54 20 UTF-16.** TEXT
33bb0 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e in bytes.** <tr>
33bc0 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 <td><b>sqlite3_c
33bd0 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74 olumn_type</b><t
33be0 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65 66 61 d>→<td>Defa
33bf0 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70 65 20 ult.** datatype
33c00 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a of the result.**
33c10 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b </table></block
33c20 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e quote>.**.** <b>
33c30 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a Details:</b>.**.
33c40 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
33c50 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d es return inform
33c60 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 ation about a si
33c70 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 ngle column of t
33c80 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 he current.** re
33c90 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 sult row of a qu
33ca0 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 ery. ^In every
33cb0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 case the first a
33cc0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
33cd0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b nter.** to the [
33ce0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
33cf0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e nt] that is bein
33d00 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 g evaluated (the
33d10 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d [sqlite3_stmt*]
33d20 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 .** that was ret
33d30 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 urned from [sqli
33d40 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
33d50 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 ] or one of its
33d60 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 variants).** and
33d70 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
33d80 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 ment is the inde
33d90 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 x of the column
33da0 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d for which inform
33db0 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 ation.** should
33dc0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 be returned. ^Th
33dd0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d e leftmost colum
33de0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 n of the result
33df0 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 set has the inde
33e00 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d x 0..** ^The num
33e10 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
33e20 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e n the result can
33e30 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 be determined u
33e40 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
33e50 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d _column_count()]
33e60 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 ..**.** If the S
33e70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 QL statement doe
33e80 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 s not currently
33e90 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 point to a valid
33ea0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a row, or if the.
33eb0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 ** column index
33ec0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c is out of range,
33ed0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 the result is u
33ee0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 ndefined..** The
33ef0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 se routines may
33f00 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 only be called w
33f10 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 hen the most rec
33f20 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ent call to.** [
33f30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
33f40 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 has returned [SQ
33f50 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 LITE_ROW] and ne
33f60 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 ither.** [sqlite
33f70 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 3_reset()] nor [
33f80 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
33f90 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 ()] have been ca
33fa0 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c lled subsequentl
33fb0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 y..** If any of
33fc0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 these routines a
33fd0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 re called after
33fe0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
33ff0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
34000 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 _finalize()] or
34010 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 after [sqlite3_s
34020 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 tep()] has retur
34030 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 ned.** something
34040 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
34050 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 ITE_ROW], the re
34060 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
34070 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 ned..** If [sqli
34080 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b te3_step()] or [
34090 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
340a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
340b0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 alize()].** are
340c0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 called from a di
340d0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 fferent thread w
340e0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 hile any of thes
340f0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 e routines.** ar
34100 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 e pending, then
34110 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
34120 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
34130 20 54 68 65 20 66 69 72 73 74 20 73 69 78 20 69 The first six i
34140 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c 6f 62 nterfaces (_blob
34150 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c , _double, _int,
34160 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c 20 _int64, _text,
34170 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a 20 and _text16).**
34180 65 61 63 68 20 72 65 74 75 72 6e 20 74 68 65 20 each return the
34190 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73 75 6c value of a resul
341a0 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73 70 t column in a sp
341b0 65 63 69 66 69 63 20 64 61 74 61 20 66 6f 72 6d ecific data form
341c0 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 72 at. If.** the r
341d0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 esult column is
341e0 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20 69 6e not initially in
341f0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 66 the requested f
34200 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61 6d 70 ormat (for examp
34210 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71 75 le,.** if the qu
34220 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e 20 69 ery returns an i
34230 6e 74 65 67 65 72 20 62 75 74 20 74 68 65 20 73 nteger but the s
34240 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
34250 78 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a xt() interface.*
34260 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65 78 74 * is used to ext
34270 72 61 63 74 20 74 68 65 20 76 61 6c 75 65 29 20 ract the value)
34280 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74 69 then an automati
34290 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f c type conversio
342a0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a n is performed..
342b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
342c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
342d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
342e0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
342f0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 INTEGER | dataty
34300 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 pe code] for the
34310 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 initial data ty
34320 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 pe.** of the res
34330 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 ult column. ^Th
34340 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 e returned value
34350 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 is one of [SQLI
34360 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 TE_INTEGER],.**
34370 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 [SQLITE_FLOAT],
34380 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b [SQLITE_TEXT], [
34390 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 SQLITE_BLOB], or
343a0 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a [SQLITE_NULL]..
343b0 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 ** The return va
343c0 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 lue of sqlite3_c
343d0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63 61 6e olumn_type() can
343e0 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 63 69 be used to deci
343f0 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20 74 de which.** of t
34400 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e 74 he first six int
34410 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 62 65 erface should be
34420 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63 74 used to extract
34430 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 the column valu
34440 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 e..** The value
34450 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
34460 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
34470 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e ) is only meanin
34480 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61 75 gful if no.** au
34490 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e tomatic type con
344a0 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 versions have oc
344b0 63 75 72 72 65 64 20 66 6f 72 20 74 68 65 20 76 curred for the v
344c0 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69 6f 6e alue in question
344d0 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61 20 74 . .** After a t
344e0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 20 ype conversion,
344f0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 63 61 the result of ca
34500 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f lling sqlite3_co
34510 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 69 lumn_type().** i
34520 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74 68 6f s undefined, tho
34530 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20 20 46 ugh harmless. F
34540 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e uture.** version
34550 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 s of SQLite may
34560 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 change the behav
34570 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 ior of sqlite3_c
34580 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 olumn_type().**
34590 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 following a type
345a0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a conversion..**.
345b0 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 ** If the result
345c0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 61 20 is a BLOB or a
345d0 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74 68 65 TEXT string, the
345e0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f n the sqlite3_co
345f0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 lumn_bytes().**
34600 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
34610 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e 74 65 n_bytes16() inte
34620 72 66 61 63 65 73 20 63 61 6e 20 62 65 20 75 73 rfaces can be us
34630 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 ed to determine
34640 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 the size.** of t
34650 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 hat BLOB or stri
34660 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ng..**.** ^If th
34670 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c e result is a BL
34680 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 OB or UTF-8 stri
34690 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 ng then the sqli
346a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
346b0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 ().** routine re
346c0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
346d0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 of bytes in tha
346e0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 t BLOB or string
346f0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
34700 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 ult is a UTF-16
34710 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c string, then sql
34720 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
34730 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 s() converts.**
34740 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 the string to UT
34750 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 F-8 and then ret
34760 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
34770 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 of bytes..** ^If
34780 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
34790 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 numeric value t
347a0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
347b0 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a mn_bytes() uses.
347c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 ** [sqlite3_snpr
347d0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 intf()] to conve
347e0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f rt that value to
347f0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 a UTF-8 string
34800 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 and returns.** t
34810 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
34820 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e es in that strin
34830 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 g..** ^If the re
34840 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 sult is NULL, th
34850 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
34860 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e n_bytes() return
34870 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 s zero..**.** ^I
34880 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
34890 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 a BLOB or UTF-16
348a0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 string then the
348b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
348c0 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 bytes16().** rou
348d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
348e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
348f0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 in that BLOB or
34900 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
34910 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
34920 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 UTF-8 string, th
34930 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
34940 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 n_bytes16() conv
34950 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 erts.** the stri
34960 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 ng to UTF-16 and
34970 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 then returns th
34980 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
34990 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 s..** ^If the re
349a0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 sult is a numeri
349b0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c c value then sql
349c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
349d0 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 s16() uses.** [s
349e0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
349f0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 )] to convert th
34a00 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 at value to a UT
34a10 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 F-16 string and
34a20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e returns.** the n
34a30 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
34a40 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a n that string..*
34a50 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
34a60 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 is NULL, then s
34a70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
34a80 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 tes16() returns
34a90 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 zero..**.** ^The
34aa0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 values returned
34ab0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c by [sqlite3_col
34ac0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 umn_bytes()] and
34ad0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f .** [sqlite3_co
34ae0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 lumn_bytes16()]
34af0 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 do not include t
34b00 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 he zero terminat
34b10 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a ors at the end.*
34b20 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e * of the string.
34b30 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 ^For clarity:
34b40 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 the values retur
34b50 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ned by.** [sqlit
34b60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
34b70 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
34b80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
34b90 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 ] are the number
34ba0 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 of.** bytes in
34bb0 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 the string, not
34bc0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 the number of ch
34bd0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 aracters..**.**
34be0 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 ^Strings returne
34bf0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
34c00 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 umn_text() and s
34c10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
34c20 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 xt16(),.** even
34c30 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 empty strings, a
34c40 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 re always zero-t
34c50 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 erminated. ^The
34c60 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 return.** value
34c70 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f from sqlite3_co
34c80 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 lumn_blob() for
34c90 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c a zero-length BL
34ca0 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 OB is a NULL poi
34cb0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 nter..**.** <b>W
34cc0 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 arning:</b> ^The
34cd0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 object returned
34ce0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c by [sqlite3_col
34cf0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 umn_value()] is
34d00 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 an.** [unprotect
34d10 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
34d20 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 ] object. In a
34d30 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e multithreaded en
34d40 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e vironment,.** an
34d50 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c unprotected sql
34d60 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
34d70 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 t may only be us
34d80 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a ed safely with.*
34d90 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
34da0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 value()] and [sq
34db0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
34dc0 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 ue()]..** If the
34dd0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
34de0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
34df0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a ect returned by.
34e00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
34e10 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 mn_value()] is u
34e20 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 sed in any other
34e30 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 way, including
34e40 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 calls.** to rout
34e50 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 ines like [sqlit
34e60 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c e3_value_int()],
34e70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
34e80 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b text()],.** or [
34e90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
34ea0 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61 tes()], the beha
34eb0 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65 vior is not thre
34ec0 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63 65 adsafe..** Hence
34ed0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f , the sqlite3_co
34ee0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e 74 lumn_value() int
34ef0 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f 72 erface.** is nor
34f00 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66 75 mally only usefu
34f10 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69 6d 70 l within the imp
34f20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a lementation of .
34f30 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d ** [application-
34f40 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
34f50 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74 75 tions] or [virtu
34f60 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74 20 al tables], not
34f70 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65 within.** top-le
34f80 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 vel application
34f90 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 code..**.** The
34fa0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d these routines m
34fb0 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f ay attempt to co
34fc0 6e 76 65 72 74 20 74 68 65 20 64 61 74 61 74 79 nvert the dataty
34fd0 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 pe of the result
34fe0 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70 6c ..** ^For exampl
34ff0 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e e, if the intern
35000 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f al representatio
35010 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 n is FLOAT and a
35020 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 text result.**
35030 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 is requested, [s
35040 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
35050 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 )] is used inter
35060 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d nally to perform
35070 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 the.** conversi
35080 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 on automatically
35090 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 . ^(The followi
350a0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 ng table details
350b0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 the conversions
350c0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 .** that are app
350d0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lied:.**.** <blo
350e0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 ckquote>.** <tab
350f0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a le border="1">.*
35100 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 * <tr><th> Inter
35110 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e nal<br>Type <th>
35120 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 Requested<br>Ty
35130 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 pe <th> Convers
35140 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 ion.**.** <tr><t
35150 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
35160 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
35170 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c Result is 0.** <
35180 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
35190 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
351a0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 <td> Result is 0
351b0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 .0.** <tr><td>
351c0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 NULL <td> T
351d0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 EXT <td> Resu
351e0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 lt is a NULL poi
351f0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e nter.** <tr><td>
35200 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 NULL <td>
35210 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 BLOB <td> Re
35220 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 sult is a NULL p
35230 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 ointer.** <tr><t
35240 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e d> INTEGER <td>
35250 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
35260 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 Convert from int
35270 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a eger to float.**
35280 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
35290 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 R <td> TEXT
352a0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e <td> ASCII ren
352b0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e dering of the in
352c0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 teger.** <tr><td
352d0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
352e0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 BLOB <td> S
352f0 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e ame as INTEGER->
35300 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e TEXT.** <tr><td>
35310 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 FLOAT <td> I
35320 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 NTEGER <td> [C
35330 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a AST] to INTEGER.
35340 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f ** <tr><td> FLO
35350 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 AT <td> TEXT
35360 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 <td> ASCII r
35370 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
35380 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 float.** <tr><td
35390 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
353a0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b BLOB <td> [
353b0 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a CAST] to BLOB.**
353c0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 <tr><td> TEXT
353d0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
353e0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f <td> [CAST] to
353f0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e INTEGER.** <tr>
35400 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
35410 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
35420 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c > [CAST] to REAL
35430 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
35440 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f XT <td> BLO
35450 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 B <td> No cha
35460 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 nge.** <tr><td>
35470 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e BLOB <td> IN
35480 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 TEGER <td> [CA
35490 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a ST] to INTEGER.*
354a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
354b0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <td> FLOAT
354c0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 <td> [CAST] t
354d0 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 o REAL.** <tr><t
354e0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e d> BLOB <td>
354f0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 TEXT <td>
35500 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 Add a zero termi
35510 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a nator if needed.
35520 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c ** </table>.** <
35530 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a /blockquote>)^.*
35540 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 *.** Note that w
35550 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 hen type convers
35560 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e ions occur, poin
35570 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 ters returned by
35580 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 prior.** calls
35590 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
355a0 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 n_blob(), sqlite
355b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 3_column_text(),
355c0 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 and/or.** sqlit
355d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
355e0 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 () may be invali
355f0 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 dated..** Type c
35600 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 onversions and p
35610 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 ointer invalidat
35620 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 ions might occur
35630 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f .** in the follo
35640 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a wing cases:.**.*
35650 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 * <ul>.** <li> T
35660 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
35670 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 nt is a BLOB and
35680 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
35690 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 text() or.**
356a0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e sqlite3_column
356b0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c _text16() is cal
356c0 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 led. A zero-ter
356d0 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a minator might.**
356e0 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 need to be
356f0 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 added to the st
35700 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c ring.</li>.** <l
35710 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 i> The initial c
35720 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 ontent is UTF-8
35730 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 text and sqlite3
35740 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
35750 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c ) or.** sql
35760 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
35770 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 16() is called.
35780 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 The content mus
35790 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a t be converted.*
357a0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 * to UTF-16
357b0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 .</li>.** <li> T
357c0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
357d0 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 nt is UTF-16 tex
357e0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f t and sqlite3_co
357f0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a lumn_bytes() or.
35800 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f ** sqlite3_
35810 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 column_text() is
35820 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f called. The co
35830 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f ntent must be co
35840 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 nverted.**
35850 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a to UTF-8.</li>.*
35860 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 * </ul>.**.** ^C
35870 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 onversions betwe
35880 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 en UTF-16be and
35890 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 UTF-16le are alw
358a0 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 ays done in plac
358b0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 e and do.** not
358c0 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 invalidate a pri
358d0 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 or pointer, thou
358e0 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 gh of course the
358f0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
35900 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 buffer.** that t
35910 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 he prior pointer
35920 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c references will
35930 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 have been modif
35940 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 ied. Other kind
35950 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 s.** of conversi
35960 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 on are done in p
35970 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 lace when it is
35980 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f possible, but so
35990 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 metimes they.**
359a0 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 are not possible
359b0 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 and in those ca
359c0 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 ses prior pointe
359d0 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 rs are invalidat
359e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 ed..**.** The sa
359f0 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 fest policy is t
35a00 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 o invoke these r
35a10 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e outines.** in on
35a20 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
35a30 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c ng ways:.**.** <
35a40 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 ul>.** <li>sqli
35a50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
35a60 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 ) followed by sq
35a70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
35a80 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c es()</li>.** <l
35a90 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e i>sqlite3_column
35aa0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 _blob() followed
35ab0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
35ac0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a mn_bytes()</li>.
35ad0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f ** <li>sqlite3_
35ae0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
35af0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 followed by sqli
35b00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
35b10 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 16()</li>.** </u
35b20 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 l>.**.** In othe
35b30 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f r words, you sho
35b40 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 uld call sqlite3
35b50 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a _column_text(),.
35b60 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
35b70 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c n_blob(), or sql
35b80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
35b90 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 16() first to fo
35ba0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a rce the result.*
35bb0 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 * into the desir
35bc0 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 ed format, then
35bd0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 invoke sqlite3_c
35be0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 olumn_bytes() or
35bf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
35c00 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 mn_bytes16() to
35c10 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 find the size of
35c20 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f the result. Do
35c30 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a not mix calls.*
35c40 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c * to sqlite3_col
35c50 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 umn_text() or sq
35c60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
35c70 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 b() with calls t
35c80 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c o.** sqlite3_col
35c90 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 umn_bytes16(), a
35ca0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 nd do not mix ca
35cb0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
35cc0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a olumn_text16().*
35cd0 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 * with calls to
35ce0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
35cf0 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ytes()..**.** ^T
35d00 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 he pointers retu
35d10 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 rned are valid u
35d20 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 ntil a type conv
35d30 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 ersion occurs as
35d40 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 .** described ab
35d50 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 ove, or until [s
35d60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f qlite3_step()] o
35d70 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
35d80 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
35d90 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 e3_finalize()] i
35da0 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 s called. ^The
35db0 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 memory space use
35dc0 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 d to hold string
35dd0 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 s.** and BLOBs i
35de0 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 s freed automati
35df0 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20 70 cally. Do not p
35e00 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 ass the pointers
35e10 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f returned.** fro
35e20 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d m [sqlite3_colum
35e30 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 n_blob()], [sqli
35e40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
35e50 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a )], etc. into.**
35e60 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
35e70 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 ]..**.** ^(If a
35e80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
35e90 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 n error occurs d
35ea0 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 uring the evalua
35eb0 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f tion of any.** o
35ec0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
35ed0 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 , a default valu
35ee0 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 e is returned.
35ef0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 The default valu
35f00 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 e.** is either t
35f10 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 he integer 0, th
35f20 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 e floating point
35f30 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 number 0.0, or
35f40 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 a NULL.** pointe
35f50 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 r. Subsequent c
35f60 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
35f70 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c _errcode()] will
35f80 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 return.** [SQLI
35f90 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a TE_NOMEM].)^.*/.
35fa0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
35fb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
35fc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
35fd0 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 nt iCol);.double
35fe0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
35ff0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 double(sqlite3_s
36000 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
36010 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
36020 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f umn_int(sqlite3_
36030 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
36040 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 ;.sqlite3_int64
36050 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 sqlite3_column_i
36060 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d nt64(sqlite3_stm
36070 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 t*, int iCol);.c
36080 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 onst unsigned ch
36090 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
360a0 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f mn_text(sqlite3_
360b0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
360c0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
360d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
360e0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t16(sqlite3_stmt
360f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 *, int iCol);.sq
36100 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c lite3_value *sql
36110 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
36120 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
36130 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 int iCol);.int
36140 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
36150 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d ytes(sqlite3_stm
36160 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 t*, int iCol);.i
36170 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
36180 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 n_bytes16(sqlite
36190 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
361a0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
361b0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 column_type(sqli
361c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
361d0 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 Col);../*.** CAP
361e0 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 I3REF: Destroy A
361f0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
36200 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 ent Object.** DE
36210 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 STRUCTOR: sqlite
36220 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
36230 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 e sqlite3_finali
36240 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 ze() function is
36250 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 called to delet
36260 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 e a [prepared st
36270 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 atement]..** ^If
36280 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
36290 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 evaluation of t
362a0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 he statement enc
362b0 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f ountered no erro
362c0 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 rs.** or if the
362d0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 statement is nev
362e0 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 er been evaluate
362f0 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f d, then sqlite3_
36300 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 finalize() retur
36310 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e ns.** SQLITE_OK.
36320 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 ^If the most r
36330 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e ecent evaluation
36340 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 of statement S
36350 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 failed, then.**
36360 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
36370 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 (S) returns the
36380 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 appropriate [err
36390 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b or code] or.** [
363a0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
363b0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ode]..**.** ^The
363c0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
363d0 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e e(S) routine can
363e0 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e be called at an
363f0 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a y point during.*
36400 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 * the life cycle
36410 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 of [prepared st
36420 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 atement] S:.** b
36430 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 efore statement
36440 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 S is ever evalua
36450 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e ted, after.** on
36460 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 e or more calls
36470 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 to [sqlite3_rese
36480 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 t()], or after a
36490 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 ny call.** to [s
364a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 qlite3_step()] r
364b0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
364c0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
364d0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a statement has.**
364e0 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 completed execu
364f0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 tion..**.** ^Inv
36500 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 oking sqlite3_fi
36510 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 nalize() on a NU
36520 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 LL pointer is a
36530 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a harmless no-op..
36540 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 **.** The applic
36550 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c ation must final
36560 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 ize every [prepa
36570 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
36580 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 n order to avoid
36590 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 .** resource lea
365a0 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 ks. It is a gri
365b0 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 evous error for
365c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
365d0 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a to try to use.**
365e0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 a prepared stat
365f0 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 ement after it h
36600 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 as been finalize
36610 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 d. Any use of a
36620 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 prepared.** sta
36630 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 tement after it
36640 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a has been finaliz
36650 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e ed can result in
36660 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a undefined and.*
36670 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 * undesirable be
36680 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 havior such as s
36690 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 egfaults and hea
366a0 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f p corruption..*/
366b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e .int sqlite3_fin
366c0 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 alize(sqlite3_st
366d0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
366e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
366f0 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 et A Prepared St
36700 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a atement Object.*
36710 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
36720 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 3_stmt.**.** The
36730 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 sqlite3_reset()
36740 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c function is cal
36750 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b led to reset a [
36760 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
36770 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 nt].** object ba
36780 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 ck to its initia
36790 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 l state, ready t
367a0 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 o be re-executed
367b0 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 ..** ^Any SQL st
367c0 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 atement variable
367d0 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 s that had value
367e0 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 s bound to them
367f0 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 using.** the [sq
36800 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
36810 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a | sqlite3_bind_*
36820 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 () API] retain t
36830 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 heir values..**
36840 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 Use [sqlite3_cle
36850 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 ar_bindings()] t
36860 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 o reset the bind
36870 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ings..**.** ^The
36880 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
36890 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 S)] interface re
368a0 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 sets the [prepar
368b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a ed statement] S.
368c0 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 ** back to the b
368d0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 eginning of its
368e0 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e program..**.** ^
368f0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
36900 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
36910 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 te3_step(S)] for
36920 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
36930 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 d statement] S r
36940 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
36950 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f ROW] or [SQLITE_
36960 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 DONE],.** or if
36970 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
36980 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f ] has never befo
36990 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f re been called o
369a0 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 n S,.** then [sq
369b0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
369c0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
369d0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 OK]..**.** ^If t
369e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 he most recent c
369f0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
36a00 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 step(S)] for the
36a10 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
36a20 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 atement] S indic
36a30 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 ated an error, t
36a40 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f hen.** [sqlite3_
36a50 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e reset(S)] return
36a60 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 s an appropriate
36a70 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a [error code]..*
36a80 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 *.** ^The [sqlit
36a90 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 e3_reset(S)] int
36aa0 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 erface does not
36ab0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
36ac0 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c s.** of any [sql
36ad0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 ite3_bind_blob|b
36ae0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 indings] on the
36af0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
36b00 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 ent] S..*/.int s
36b10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c qlite3_reset(sql
36b20 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
36b30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
36b40 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 EF: Create Or Re
36b50 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 define SQL Funct
36b60 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ions.** KEYWORDS
36b70 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 : {function crea
36b80 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a tion routines}.*
36b90 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 * KEYWORDS: {app
36ba0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
36bb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a SQL function}.*
36bc0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 * KEYWORDS: {app
36bd0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
36be0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a SQL functions}.
36bf0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
36c00 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 e3.**.** ^These
36c10 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 functions (colle
36c20 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 ctively known as
36c30 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 "function creat
36c40 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a ion routines").*
36c50 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 * are used to ad
36c60 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 d SQL functions
36c70 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 or aggregates or
36c80 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 to redefine the
36c90 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 behavior.** of
36ca0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e existing SQL fun
36cb0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 ctions or aggreg
36cc0 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 ates. The only
36cd0 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 differences betw
36ce0 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 een.** these rou
36cf0 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 tines are the te
36d00 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 xt encoding expe
36d10 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 cted for.** the
36d20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
36d30 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 (the name of th
36d40 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 e function being
36d50 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 created).** and
36d60 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 the presence or
36d70 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 absence of a de
36d80 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 structor callbac
36d90 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 k for.** the app
36da0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f lication data po
36db0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 inter..**.** ^Th
36dc0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
36dd0 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 r is the [databa
36de0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
36df0 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a o which the SQL.
36e00 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ** function is t
36e10 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 o be added. ^If
36e20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
36e30 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f uses more than o
36e40 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 ne database.** c
36e50 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 onnection then a
36e60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
36e70 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
36e80 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a must be added.*
36e90 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 * to each databa
36ea0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 se connection se
36eb0 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 parately..**.**
36ec0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 ^The second para
36ed0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d meter is the nam
36ee0 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e e of the SQL fun
36ef0 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 ction to be crea
36f00 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 ted or.** redefi
36f10 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 ned. ^The lengt
36f20 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 h of the name is
36f30 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 limited to 255
36f40 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 bytes in a UTF-8
36f50 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 .** representati
36f60 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 on, exclusive of
36f70 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
36f80 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 ator. ^Note tha
36f90 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 t the name.** le
36fa0 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e ngth limit is in
36fb0 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f UTF-8 bytes, no
36fc0 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 t characters nor
36fd0 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 UTF-16 bytes.
36fe0 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 .** ^Any attempt
36ff0 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e to create a fun
37000 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e ction with a lon
37010 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c ger name.** will
37020 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 result in [SQLI
37030 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 TE_MISUSE] being
37040 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
37050 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 ^The third para
37060 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 meter (nArg).**
37070 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
37080 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
37090 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
370a0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
370b0 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 takes. ^If this
370c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 parameter is -1
370d0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 , then the SQL f
370e0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
370f0 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 gregate may take
37100 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 any number of a
37110 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e rguments between
37120 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0 and the limit
37130 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 .** set by [sqli
37140 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 te3_limit]([SQLI
37150 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f TE_LIMIT_FUNCTIO
37160 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 N_ARG]). If the
37170 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 third.** parame
37180 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e ter is less than
37190 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 -1 or greater t
371a0 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 han 127 then the
371b0 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 behavior is.**
371c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
371d0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 ^The fourth par
371e0 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 ameter, eTextRep
371f0 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 , specifies what
37200 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 .** [SQLITE_UTF8
37210 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 | text encoding
37220 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 ] this SQL funct
37230 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a ion prefers for.
37240 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 ** its parameter
37250 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 s. The applicat
37260 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 ion should set t
37270 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f his parameter to
37280 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 .** [SQLITE_UTF1
37290 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 6LE] if the func
372a0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
372b0 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 ion invokes .**
372c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
372d0 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e ext16le()] on an
372e0 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 input, or [SQLI
372f0 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 TE_UTF16BE] if t
37300 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 he.** implementa
37310 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 tion invokes [sq
37320 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
37330 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 16be()] on an in
37340 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 put, or.** [SQLI
37350 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 TE_UTF16] if [sq
37360 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
37370 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 16()] is used, o
37380 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a r [SQLITE_UTF8].
37390 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e ** otherwise. ^
373a0 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e The same SQL fun
373b0 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 ction may be reg
373c0 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 istered multiple
373d0 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 times using.**
373e0 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 different prefer
373f0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e red text encodin
37400 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 gs, with differe
37410 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f nt implementatio
37420 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 ns for.** each e
37430 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 ncoding..** ^Whe
37440 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 n multiple imple
37450 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 mentations of th
37460 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 e same function
37470 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 are available, S
37480 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 QLite.** will pi
37490 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 ck the one that
374a0 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 involves the lea
374b0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 st amount of dat
374c0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a a conversion..**
374d0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 .** ^The fourth
374e0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 parameter may op
374f0 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 tionally be ORed
37500 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 with [SQLITE_DE
37510 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 TERMINISTIC].**
37520 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 to signal that t
37530 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c he function will
37540 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 always return t
37550 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 he same result g
37560 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 iven.** the same
37570 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 inputs within a
37580 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 single SQL stat
37590 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c ement. Most SQL
375a0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a functions are.*
375b0 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e * deterministic.
375c0 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b The built-in [
375d0 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 random()] SQL fu
375e0 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 nction is an exa
375f0 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e mple of a.** fun
37600 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f ction that is no
37610 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e t deterministic.
37620 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 The SQLite que
37630 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 ry planner is ab
37640 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d le to.** perform
37650 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 additional opti
37660 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 mizations on det
37670 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 erministic funct
37680 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 ions, so use.**
37690 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 of the [SQLITE_D
376a0 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c ETERMINISTIC] fl
376b0 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ag is recommende
376c0 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 d where possible
376d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 ..**.** ^(The fi
376e0 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 fth parameter is
376f0 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f an arbitrary po
37700 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c inter. The impl
37710 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
37720 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 e.** function ca
37730 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f n gain access to
37740 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 this pointer us
37750 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 ing [sqlite3_use
37760 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a r_data()].)^.**.
37770 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 ** ^The sixth, s
37780 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 eventh and eight
37790 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 h parameters, xF
377a0 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 unc, xStep and x
377b0 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f Final, are.** po
377c0 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 inters to C-lang
377d0 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 uage functions t
377e0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 hat implement th
377f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
37800 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 r.** aggregate.
37810 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 ^A scalar SQL fu
37820 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
37830 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f an implementatio
37840 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a n of the xFunc.*
37850 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b * callback only;
37860 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d NULL pointers m
37870 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 ust be passed as
37880 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 the xStep and x
37890 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 Final.** paramet
378a0 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 ers. ^An aggrega
378b0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 te SQL function
378c0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c requires an impl
378d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 ementation of xS
378e0 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 tep.** and xFina
378f0 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 l and NULL point
37900 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 er must be passe
37910 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f d for xFunc. ^To
37920 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 delete an exist
37930 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 ing.** SQL funct
37940 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
37950 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e , pass NULL poin
37960 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 ters for all thr
37970 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 ee function.** c
37980 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 allbacks..**.**
37990 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 ^(If the ninth p
379a0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
379b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
379c0 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 ion_v2() is not
379d0 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 NULL,.** then it
379e0 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 is destructor f
379f0 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 or the applicati
37a00 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e on data pointer.
37a10 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 .** The destruc
37a20 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 tor is invoked w
37a30 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e hen the function
37a40 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 is deleted, eit
37a50 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 her by being.**
37a60 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 overloaded or wh
37a70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
37a80 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 connection close
37a90 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 s.)^.** ^The des
37aa0 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 tructor is also
37ab0 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 invoked if the c
37ac0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 all to.** sqlite
37ad0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
37ae0 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a n_v2() fails..**
37af0 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 ^When the destr
37b00 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f uctor callback o
37b10 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 f the tenth para
37b20 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 meter is invoked
37b30 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 , it.** is passe
37b40 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d d a single argum
37b50 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 ent which is a c
37b60 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 opy of the appli
37b70 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 cation data .**
37b80 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 pointer which wa
37b90 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 s the fifth para
37ba0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
37bb0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
37bc0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 _v2()..**.** ^It
37bd0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f is permitted to
37be0 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 register multip
37bf0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
37c00 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a ns of the same.*
37c10 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 * functions with
37c20 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 the same name b
37c30 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 ut with either d
37c40 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 iffering numbers
37c50 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 of.** arguments
37c60 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 or differing pr
37c70 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 eferred text enc
37c80 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 odings. ^SQLite
37c90 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 will use.** the
37ca0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
37cb0 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c that most closel
37cc0 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 y matches the wa
37cd0 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a y in which the.*
37ce0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 * SQL function i
37cf0 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 s used. ^A func
37d00 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
37d10 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e ion with a non-n
37d20 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 egative.** nArg
37d30 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 parameter is a b
37d40 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e etter match than
37d50 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c a function impl
37d60 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a ementation with.
37d70 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 ** a negative nA
37d80 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e rg. ^A function
37d90 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 where the prefe
37da0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
37db0 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 ng.** matches th
37dc0 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 e database encod
37dd0 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a ing is a better.
37de0 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 ** match than a
37df0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 function where t
37e00 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 he encoding is d
37e10 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e ifferent. .** ^
37e20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 A function where
37e30 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 the encoding di
37e40 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 fference is betw
37e50 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 een UTF16le and
37e60 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 UTF16be.** is a
37e70 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 closer match tha
37e80 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 n a function whe
37e90 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 re the encoding
37ea0 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a difference is.**
37eb0 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e between UTF8 an
37ec0 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e d UTF16..**.** ^
37ed0 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f Built-in functio
37ee0 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f ns may be overlo
37ef0 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c aded by new appl
37f00 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
37f10 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a functions..**.**
37f20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e ^An application
37f30 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
37f40 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 n is permitted t
37f50 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 o call other.**
37f60 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
37f70 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 s. However, suc
37f80 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 h calls must not
37f90 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 .** close the da
37fa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
37fb0 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f n nor finalize o
37fc0 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 r reset the prep
37fd0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e ared.** statemen
37fe0 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 t in which the f
37ff0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
38000 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ng..*/.int sqlit
38010 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
38020 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 on(. sqlite3 *d
38030 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 b,. const char
38040 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a *zFunctionName,.
38050 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e int nArg,. in
38060 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f t eTextRep,. vo
38070 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 id *pApp,. void
38080 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 (*xFunc)(sqlite
38090 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
380a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
380b0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 . void (*xStep)
380c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
380d0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
380e0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
380f0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 *xFinal)(sqlite3
38100 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e _context*).);.in
38110 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
38120 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 _function16(. s
38130 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f qlite3 *db,. co
38140 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 nst void *zFunct
38150 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e ionName,. int n
38160 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 Arg,. int eText
38170 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 Rep,. void *pAp
38180 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e p,. void (*xFun
38190 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 c)(sqlite3_conte
381a0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
381b0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
381c0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 (*xStep)(sqlite
381d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
381e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
381f0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c . void (*xFinal
38200 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
38210 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 t*).);.int sqlit
38220 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
38230 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 on_v2(. sqlite3
38240 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 *db,. const ch
38250 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d ar *zFunctionNam
38260 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 e,. int nArg,.
38270 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 int eTextRep,.
38280 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 void *pApp,. v
38290 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c oid (*xFunc)(sql
382a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
382b0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
382c0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 *),. void (*xSt
382d0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ep)(sqlite3_cont
382e0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
382f0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
38300 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 d (*xFinal)(sqli
38310 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 te3_context*),.
38320 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 void(*xDestroy)
38330 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a (void*).);../*.*
38340 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 * CAPI3REF: Text
38350 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a Encodings.**.**
38360 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 These constant
38370 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 define integer c
38380 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 odes that repres
38390 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a ent the various.
383a0 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 ** text encoding
383b0 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 s supported by S
383c0 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e QLite..*/.#defin
383d0 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 e SQLITE_UTF8
383e0 20 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 1 /*
383f0 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 IMP: R-37514-355
38400 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 66 */.#define SQ
38410 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 LITE_UTF16LE
38420 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 2 /* IMP:
38430 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a R-03371-37637 *
38440 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
38450 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 _UTF16BE
38460 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 3 /* IMP: R-5
38470 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 1971-34154 */.#d
38480 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
38490 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 16 4
384a0 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 /* Use native b
384b0 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 yte order */.#de
384c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 fine SQLITE_ANY
384d0 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 5
384e0 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f /* Deprecated */
384f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
38500 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 UTF16_ALIGNED 8
38510 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 /* sqlite3_c
38520 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 reate_collation
38530 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 only */../*.** C
38540 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f API3REF: Functio
38550 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 n Flags.**.** Th
38560 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 ese constants ma
38570 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 y be ORed togeth
38580 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 er with the .**
38590 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 [SQLITE_UTF8 | p
385a0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
385b0 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 coding] as the f
385c0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a ourth argument.*
385d0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 * to [sqlite3_cr
385e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
385f0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 , [sqlite3_creat
38600 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c e_function16()],
38610 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
38620 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f create_function_
38630 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e v2()]..*/.#defin
38640 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 e SQLITE_DETERMI
38650 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a NISTIC 0x800.
38660 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
38670 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 Deprecated Func
38680 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 tions.** DEPRECA
38690 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TED.**.** These
386a0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 functions are [d
386b0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 eprecated]. In
386c0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 order to maintai
386d0 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 n.** backwards c
386e0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 ompatibility wit
386f0 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 h older code, th
38700 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f ese functions co
38710 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 ntinue .** to be
38720 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 supported. How
38730 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 ever, new applic
38740 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 ations should av
38750 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f oid.** the use o
38760 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e f these function
38770 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 s. To encourage
38780 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 programmers to