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 0a 2a 2a 0a source tree..**.
10c0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
10d0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
10e0: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
10f0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
1100: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f er()], [sqlite3_
1110: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 sourceid()],.**
1120: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 [sqlite_version(
1130: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 )] and [sqlite_s
1140: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a ource_id()]..*/.
1150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 #define SQLITE_V
1160: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d ERSION "-
1170: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 -VERS--".#define
1180: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f SQLITE_VERSION_
1190: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e NUMBER --VERSION
11a0: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e -NUMBER--.#defin
11b0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f e SQLITE_SOURCE_
11c0: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 ID "--SOURC
11d0: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 E-ID--"../*.** C
11e0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d API3REF: Run-Tim
11f0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f e Library Versio
1200: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 n Numbers.** KEY
1210: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 WORDS: sqlite3_v
1220: 65 72 73 69 6f 6e 20 73 71 6c 69 74 65 33 5f 73 ersion sqlite3_s
1230: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 ourceid.**.** Th
1240: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 ese interfaces p
1250: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 rovide the same
1260: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 information as t
1270: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 he [SQLITE_VERSI
1280: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ON],.** [SQLITE_
1290: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c VERSION_NUMBER],
12a0: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 and [SQLITE_SOU
12b0: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f RCE_ID] C prepro
12c0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a cessor macros.**
12d0: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 but are associa
12e0: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 ted with the lib
12f0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 rary instead of
1300: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e the header file.
1310: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 ^(Cautious.**
1320: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 programmers migh
1330: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 t include assert
1340: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e () statements in
1350: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 their applicati
1360: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 on to.** verify
1370: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 that values retu
1380: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e rned by these in
1390: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 terfaces match t
13a0: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 he macros in.**
13b0: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 the header, and
13c0: 74 68 75 73 20 65 6e 73 75 72 65 20 74 68 61 74 thus ensure that
13d0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
13e0: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 is.** compiled
13f0: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 with matching li
1400: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 brary and header
1410: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 files..**.** <b
1420: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1430: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 ** assert( sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 e3_libversion_nu
1450: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 mber()==SQLITE_V
1460: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b ERSION_NUMBER );
1470: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 .** assert( strc
1480: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 mp(sqlite3_sourc
1490: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 eid(),SQLITE_SOU
14a0: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a RCE_ID)==0 );.**
14b0: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 assert( strcmp(
14c0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
14d0: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 on(),SQLITE_VERS
14e0: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f ION)==0 );.** </
14f0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1500: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 >)^.**.** ^The s
1510: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d qlite3_version[]
1520: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
1530: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 contains the te
1540: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 xt of [SQLITE_VE
1550: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e RSION].** macro.
1560: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c ^The sqlite3_l
1570: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 ibversion() func
1580: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 tion returns a p
1590: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a ointer to the.**
15a0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
15b0: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 version[] string
15c0: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 constant. The
15d0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
15e0: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e on().** function
15f0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 is provided for
1600: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e use in DLLs sin
1610: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 ce DLL users usu
1620: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 ally do not have
1630: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 .** direct acces
1640: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 s to string cons
1650: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 tants within the
1660: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 DLL. ^The.** s
1670: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1680: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 n_number() funct
1690: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 ion returns an i
16a0: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a nteger equal to.
16b0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 ** [SQLITE_VERSI
16c0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 ON_NUMBER]. ^Th
16d0: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 e sqlite3_source
16e0: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 id() function re
16f0: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e turns .** a poin
1700: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 ter to a string
1710: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76 constant whose v
1720: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65 alue is the same
1730: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c as the .** [SQL
1740: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 ITE_SOURCE_ID] C
1750: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
1760: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 cro..**.** See a
1770: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 lso: [sqlite_ver
1780: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c sion()] and [sql
1790: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d ite_source_id()]
17a0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 ..*/.SQLITE_EXTE
17b0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 RN const char sq
17c0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b lite3_version[];
17d0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
17e0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
17f0: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61 void);.const cha
1800: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 r *sqlite3_sourc
1810: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 eid(void);.int s
1820: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1830: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a n_number(void);.
1840: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1850: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 Run-Time Librar
1860: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 y Compilation Op
1870: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 tions Diagnostic
1880: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
1890: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
18a0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 on_used() functi
18b0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 on returns 0 or
18c0: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 1 .** indicating
18d0: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 whether the spe
18e0: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 cified option wa
18f0: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a s defined at .**
1900: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 compile time.
1910: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 ^The SQLITE_ pre
1920: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 fix may be omitt
1930: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 ed from the .**
1940: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 option name pass
1950: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ed to sqlite3_co
1960: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 mpileoption_used
1970: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 (). .**.** ^The
1980: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
1990: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e option_get() fun
19a0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 ction allows ite
19b0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 rating.** over t
19c0: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f he list of optio
19d0: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 ns that were def
19e0: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 ined at compile
19f0: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 time by.** retur
1a00: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f ning the N-th co
1a10: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f mpile time optio
1a20: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e n string. ^If N
1a30: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
1a40: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d ,.** sqlite3_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
1a60: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
1a70: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 pointer. ^The S
1a80: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 QLITE_ .** prefi
1a90: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f x is omitted fro
1aa0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 m any strings re
1ab0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 turned by .** sq
1ac0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
1ad0: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a ion_get()..**.**
1ae0: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 ^Support for th
1af0: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e e diagnostic fun
1b00: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 ctions sqlite3_c
1b10: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
1b20: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 d().** and sqlit
1b30: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
1b40: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d _get() may be om
1b50: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 itted by specify
1b60: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c ing the .** [SQL
1b70: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 ITE_OMIT_COMPILE
1b80: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 OPTION_DIAGS] op
1b90: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 tion at compile
1ba0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 time..**.** See
1bb0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 also: SQL functi
1bc0: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 ons [sqlite_comp
1bd0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 ileoption_used()
1be0: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
1bf0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
1c00: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 et()] and the [c
1c10: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 ompile_options p
1c20: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 ragma]..*/.#ifnd
1c30: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 ef SQLITE_OMIT_C
1c40: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 OMPILEOPTION_DIA
1c50: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 GS.int sqlite3_c
1c60: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
1c70: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f d(const char *zO
1c80: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 ptName);.const c
1c90: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d har *sqlite3_com
1ca0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69 pileoption_get(i
1cb0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f nt N);.#endif../
1cc0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
1cd0: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 est To See If Th
1ce0: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 e Library Is Thr
1cf0: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 eadsafe.**.** ^T
1d00: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 he sqlite3_threa
1d10: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e dsafe() function
1d20: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66 returns zero if
1d30: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 and only if.**
1d40: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 SQLite was compi
1d50: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e led with mutexin
1d60: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 g code omitted d
1d70: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 ue to the.** [SQ
1d80: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d LITE_THREADSAFE]
1d90: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
1da0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74 tion being set t
1db0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 o 0..**.** SQLit
1dc0: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 e can be compile
1dd0: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 d with or withou
1de0: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e t mutexes. When
1df0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
1e00: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72 THREADSAFE] C pr
1e10: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f eprocessor macro
1e20: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 is 1 or 2, mute
1e30: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c xes.** are enabl
1e40: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 ed and SQLite is
1e50: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 threadsafe. Wh
1e60: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 en the.** [SQLIT
1e70: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 E_THREADSAFE] ma
1e80: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 cro is 0, .** th
1e90: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d e mutexes are om
1ea0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 itted. Without
1eb0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 the mutexes, it
1ec0: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 is not safe.** t
1ed0: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e o use SQLite con
1ee0: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d currently from m
1ef0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 ore than one thr
1f00: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c ead..**.** Enabl
1f10: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 ing mutexes incu
1f20: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 rs a measurable
1f30: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 performance pena
1f40: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 lty..** So if sp
1f50: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 eed is of utmost
1f60: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 importance, it
1f70: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 makes sense to d
1f80: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 isable.** the mu
1f90: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 texes. But for
1fa0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 maximum safety,
1fb0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 mutexes should b
1fc0: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 e enabled..** ^T
1fd0: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 he default behav
1fe0: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 ior is for mutex
1ff0: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 es to be enabled
2000: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
2010: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 erface can be us
2020: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61 ed by an applica
2030: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 tion to make sur
2040: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 e that the.** ve
2050: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 rsion of SQLite
2060: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 that it is linki
2070: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 ng against was c
2080: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
2090: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 the desired sett
20a0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 ing of the [SQLI
20b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d TE_THREADSAFE] m
20c0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 acro..**.** This
20d0: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 interface only
20e0: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 reports on the c
20f0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 ompile-time mute
2100: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 x setting.** of
2110: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
2120: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 ADSAFE] flag. I
2130: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
2140: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c iled with.** SQL
2150: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 ITE_THREADSAFE=1
2160: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 or =2 then mute
2170: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 xes are enabled
2180: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a by default but.*
2190: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f * can be fully o
21a0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61 r partially disa
21b0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c bled using a cal
21c0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f l to [sqlite3_co
21d0: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 nfig()].** with
21e0: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54 the verbs [SQLIT
21f0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
2200: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f HREAD], [SQLITE_
2210: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
2220: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 AD],.** or [SQLI
2230: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
2240: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65 IZED]. ^(The re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
2260: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 e.** sqlite3_thr
2270: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 eadsafe() functi
2280: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 on shows only th
2290: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 e compile-time s
22a0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 etting of.** thr
22b0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 ead safety, not
22c0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 any run-time cha
22d0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 nges to that set
22e0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 ting made by.**
22f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
2300: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 . In other words
2310: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
2320: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
2330: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 threadsafe().**
2340: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 is unchanged by
2350: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
2360: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a _config().)^.**.
2370: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 ** See the [thre
2380: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 ading mode] docu
2390: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 mentation for ad
23a0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
23b0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c tion..*/.int sql
23c0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 ite3_threadsafe(
23d0: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 void);../*.** CA
23e0: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 PI3REF: Database
23f0: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 Connection Hand
2400: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 le.** KEYWORDS:
2410: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 {database connec
2420: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 tion} {database
2430: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a connections}.**.
2440: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c ** Each open SQL
2450: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20 ite database is
2460: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 represented by a
2470: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
2480: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 nstance of.** th
2490: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 e opaque structu
24a0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 re named "sqlite
24b0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 3". It is usefu
24c0: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e l to think of an
24d0: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e sqlite3.** poin
24e0: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 ter as an object
24f0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
2500: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
2510: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 3_open16()], and
2520: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
2530: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 n_v2()] interfac
2540: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 es are its const
2550: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 ructors, and [sq
2560: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a lite3_close()].*
2570: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 * and [sqlite3_c
2580: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69 lose_v2()] are i
2590: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20 ts destructors.
25a0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 There are many
25b0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 other.** interfa
25c0: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 ces (such as.**
25d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
25e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v2()], [sqlite3
25f0: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2600: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
2610: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
2620: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 t()] to name but
2630: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65 three) that are
2640: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a methods on an.*
2650: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 * sqlite3 object
2660: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
2670: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 uct sqlite3 sqli
2680: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 te3;../*.** CAPI
2690: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 3REF: 64-Bit Int
26a0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 eger Types.** KE
26b0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 YWORDS: sqlite_i
26c0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 nt64 sqlite_uint
26d0: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 64.**.** Because
26e0: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f there is no cro
26f0: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 ss-platform way
2700: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 to specify 64-bi
2710: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a t integer types.
2720: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 ** SQLite includ
2730: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 es typedefs for
2740: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64-bit signed an
2750: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 d unsigned integ
2760: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ers..**.** The s
2770: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 qlite3_int64 and
2780: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 sqlite3_uint64
2790: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 are the preferre
27a0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f d type definitio
27b0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 ns..** The sqlit
27c0: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 e_int64 and sqli
27d0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 te_uint64 types
27e0: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f are supported fo
27f0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 r backwards.** c
2800: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c ompatibility onl
2810: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 y..**.** ^The sq
2820: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 lite3_int64 and
2830: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 sqlite_int64 typ
2840: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 es can store int
2850: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 eger values.** b
2860: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 etween -92233720
2870: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 36854775808 and
2880: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 +922337203685477
2890: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 5807 inclusive.
28a0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
28b0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 _uint64 and sqli
28c0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 te_uint64 types
28d0: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 can store intege
28e0: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 r values .** bet
28f0: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 ween 0 and +1844
2900: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35 6744073709551615
2910: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 inclusive..*/.#
2920: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 ifdef SQLITE_INT
2930: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 64_TYPE. typede
2940: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 f SQLITE_INT64_T
2950: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 YPE sqlite_int64
2960: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45 ;.# ifdef SQLITE
2970: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20 _UINT64_TYPE.
2980: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f typedef SQLITE_
2990: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 UINT64_TYPE sqli
29a0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73 te_uint64;.# els
29b0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20 e . typedef
29c0: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f unsigned SQLITE_
29d0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 INT64_TYPE sqlit
29e0: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69 e_uint64;.# endi
29f0: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 f.#elif defined(
2a00: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 _MSC_VER) || def
2a10: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f ined(__BORLANDC_
2a20: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 _). typedef __i
2a30: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 nt64 sqlite_int6
2a40: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 4;. typedef uns
2a50: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 igned __int64 sq
2a60: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c lite_uint64;.#el
2a70: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e se. typedef lon
2a80: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 g long int sqlit
2a90: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
2aa0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 ef unsigned long
2ab0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 long int sqlite
2ac0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a _uint64;.#endif.
2ad0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 typedef sqlite_i
2ae0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 nt64 sqlite3_int
2af0: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 64;.typedef sqli
2b00: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 te_uint64 sqlite
2b10: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 3_uint64;../*.**
2b20: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f If compiling fo
2b30: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 r a processor th
2b40: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e at lacks floatin
2b50: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c g point support,
2b60: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 .** substitute i
2b70: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 nteger for float
2b80: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 ing-point..*/.#i
2b90: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 fdef SQLITE_OMIT
2ba0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a _FLOATING_POINT.
2bb0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 # define double
2bc0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 sqlite3_int64.#e
2bd0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
2be0: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 3REF: Closing A
2bf0: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
2c00: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f ion.** DESTRUCTO
2c10: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a R: sqlite3.**.**
2c20: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c ^The sqlite3_cl
2c30: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ose() and sqlite
2c40: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75 3_close_v2() rou
2c50: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75 tines are destru
2c60: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65 ctors.** for the
2c70: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
2c80: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 t..** ^Calls to
2c90: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 sqlite3_close()
2ca0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 and sqlite3_clos
2cb0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53 e_v2() return [S
2cc0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 QLITE_OK] if.**
2cd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 the [sqlite3] ob
2ce0: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66 ject is successf
2cf0: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61 ully destroyed a
2d00: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 nd all associate
2d10: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61 d.** resources a
2d20: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a re deallocated..
2d30: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 **.** ^If the da
2d40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2d50: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 n is associated
2d60: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 with unfinalized
2d70: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 prepared.** sta
2d80: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e tements or unfin
2d90: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 ished sqlite3_ba
2da0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65 ckup objects the
2db0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 n sqlite3_close(
2dc0: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20 ).** will leave
2dd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2de0: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 nection open and
2df0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
2e00: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 BUSY]..** ^If sq
2e10: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
2e20: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 is called with
2e30: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 unfinalized prep
2e40: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a ared statements.
2e50: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 ** and/or unfini
2e60: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 shed sqlite3_bac
2e70: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 kups, then the d
2e80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2e90: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e on becomes.** an
2ea0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 unusable "zombi
2eb0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 e" which will au
2ec0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 tomatically be d
2ed0: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 eallocated when
2ee0: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 the.** last prep
2ef0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 ared statement i
2f00: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 s finalized or t
2f10: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f he last sqlite3_
2f20: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e backup is.** fin
2f30: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 ished. The sqli
2f40: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 te3_close_v2() i
2f50: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 nterface is inte
2f60: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 nded for use wit
2f70: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 h.** host langua
2f80: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72 ges that are gar
2f90: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 bage collected,
2fa0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 and where the or
2fb0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 der in which.**
2fc0: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 destructors are
2fd0: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 called is arbitr
2fe0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 ary..**.** Appli
2ff0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b cations should [
3000: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
3010: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c | finalize] all
3020: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
3030: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ments],.** [sqli
3040: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c te3_blob_close |
3050: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f close] all [BLO
3060: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 B handles], and
3070: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 .** [sqlite3_bac
3080: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e kup_finish | fin
3090: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 ish] all [sqlite
30a0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 3_backup] object
30b0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 s associated.**
30c0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 with the [sqlite
30d0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 3] object prior
30e0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f to attempting to
30f0: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 close the objec
3100: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 t. ^If.** sqlit
3110: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 e3_close_v2() is
3120: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 called on a [da
3130: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3140: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61 n] that still ha
3150: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 s.** outstanding
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 20 5b 42 4c 4f 42 20 68 61 ments], [BLOB ha
3180: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a ndles], and/or.*
3190: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 * [sqlite3_backu
31a0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 p] objects then
31b0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 it returns [SQLI
31c0: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64 TE_OK] and the d
31d0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f eallocation.** o
31e0: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 f resources is d
31f0: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c eferred until al
3200: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 l [prepared stat
3210: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 ements], [BLOB h
3220: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 andles],.** and
3230: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d [sqlite3_backup]
3240: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 objects are als
3250: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a o destroyed..**.
3260: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 ** ^If an [sqlit
3270: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 e3] object is de
3280: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 stroyed while a
3290: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f transaction is o
32a0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e pen,.** the tran
32b0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d saction is autom
32c0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 atically rolled
32d0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 back..**.** The
32e0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b C parameter to [
32f0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 sqlite3_close(C)
3300: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
3310: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d lose_v2(C)].** m
3320: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 ust be either a
3330: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 NULL.** pointer
3340: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 or an [sqlite3]
3350: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f object pointer o
3360: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 btained.** from
3370: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
3380: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 , [sqlite3_open1
3390: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 6()], or.** [sql
33a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c ite3_open_v2()],
33b0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 and not previou
33c0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e sly closed..** ^
33d0: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f Calling sqlite3_
33e0: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 close() or sqlit
33f0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 e3_close_v2() wi
3400: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 th a NULL pointe
3410: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 r.** argument is
3420: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f a harmless no-o
3430: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 p..*/.int sqlite
3440: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 3_close(sqlite3*
3450: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
3460: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a lose_v2(sqlite3*
3470: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 );../*.** The ty
3480: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 pe for a callbac
3490: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 k function..** T
34a0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e his is legacy an
34b0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 d deprecated. I
34c0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f t is included fo
34d0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 r historical.**
34e0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e compatibility an
34f0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e d is not documen
3500: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ted..*/.typedef
3510: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 int (*sqlite3_ca
3520: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e llback)(void*,in
3530: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a t,char**, char**
3540: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
3550: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 EF: One-Step Que
3560: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 ry Execution Int
3570: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 erface.** METHOD
3580: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
3590: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 The sqlite3_exec
35a0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
35b0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 a convenience wr
35c0: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 apper around.**
35d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
35e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v2()], [sqlite3
35f0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 _step()], and [s
3600: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
3610: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f )],.** that allo
3620: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f ws an applicatio
3630: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c n to run multipl
3640: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 e statements of
3650: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 SQL.** without h
3660: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c aving to use a l
3670: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a ot of C code. .*
3680: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
3690: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 3_exec() interfa
36a0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 ce runs zero or
36b0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 more UTF-8 encod
36c0: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e ed,.** semicolon
36d0: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 -separate SQL st
36e0: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 atements passed
36f0: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 into its 2nd arg
3700: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 ument,.** in the
3710: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 context of the
3720: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
3730: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 tion] passed in
3740: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 as its 1st.** ar
3750: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 gument. ^If the
3760: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
3770: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 on of the 3rd ar
3780: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c gument to.** sql
3790: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e ite3_exec() is n
37a0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 ot NULL, then it
37b0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 is invoked for
37c0: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a each result row.
37d0: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 ** coming out of
37e0: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 the evaluated S
37f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 QL statements.
3800: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e ^The 4th argumen
3810: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f t to.** sqlite3_
3820: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 exec() is relaye
3830: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 d through to the
3840: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 1st argument of
3850: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 each.** callbac
3860: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e k invocation. ^
3870: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
3880: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 pointer to sqlit
3890: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 e3_exec().** is
38a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 NULL, then no ca
38b0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 llback is ever i
38c0: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c nvoked and resul
38d0: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 t rows are.** ig
38e0: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 nored..**.** ^If
38f0: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
3900: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e while evaluatin
3910: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d g the SQL statem
3920: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f ents passed into
3930: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
3940: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 (), then executi
3950: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e on of the curren
3960: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 t statement stop
3970: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 s and.** subsequ
3980: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 ent statements a
3990: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 re skipped. ^If
39a0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 the 5th paramet
39b0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
39c0: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e ec().** is not N
39d0: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 ULL then any err
39e0: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 or message is wr
39f0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 itten into memor
3a00: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 y obtained.** fr
3a10: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
3a20: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 oc()] and passed
3a30: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 back through th
3a40: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e e 5th parameter.
3a50: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d .** To avoid mem
3a60: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 ory leaks, the a
3a70: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
3a80: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 d invoke [sqlite
3a90: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 3_free()].** on
3aa0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 error message st
3ab0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 rings returned t
3ac0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 hrough the 5th p
3ad0: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73 arameter of.** s
3ae0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 qlite3_exec() af
3af0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 ter the error me
3b00: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 ssage string is
3b10: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 no longer needed
3b20: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 ..** ^If the 5th
3b30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
3b40: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
3b50: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 not NULL and no
3b60: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c errors.** occur,
3b70: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 then sqlite3_ex
3b80: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f ec() sets the po
3b90: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 inter in its 5th
3ba0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
3bb0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 NULL before ret
3bc0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 urning..**.** ^I
3bd0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 f an sqlite3_exe
3be0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 c() callback ret
3bf0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 urns non-zero, t
3c00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 he sqlite3_exec(
3c10: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
3c20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 urns SQLITE_ABOR
3c30: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 T without invoki
3c40: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 ng the callback
3c50: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 again and.** wit
3c60: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 hout running any
3c70: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 subsequent SQL
3c80: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a statements..**.*
3c90: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d * ^The 2nd argum
3ca0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ent to the sqlit
3cb0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 e3_exec() callba
3cc0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ck function is t
3cd0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
3ce0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 columns in the r
3cf0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 esult. ^The 3rd
3d00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
3d10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
3d20: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 ** callback is a
3d30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
3d40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f ers to strings o
3d50: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 btained as if fr
3d60: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 om.** [sqlite3_c
3d70: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f olumn_text()], o
3d80: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 ne for each colu
3d90: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d mn. ^If an elem
3da0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 ent of a.** resu
3db0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 lt row is NULL t
3dc0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f hen the correspo
3dd0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 nding string poi
3de0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 nter for the.**
3df0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 sqlite3_exec() c
3e00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c allback is a NUL
3e10: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 L pointer. ^The
3e20: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 4th argument to
3e30: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f the.** sqlite3_
3e40: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 exec() callback
3e50: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
3e60: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e ointers to strin
3e70: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a gs where each.**
3e80: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 entry represent
3e90: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f s the name of co
3ea0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 rresponding resu
3eb0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 lt column as obt
3ec0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 ained.** from [s
3ed0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
3ee0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 me()]..**.** ^If
3ef0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
3f00: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
3f10: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 ec() is a NULL p
3f20: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 ointer, a pointe
3f30: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 r.** to an empty
3f40: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f string, or a po
3f50: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 inter that conta
3f60: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 ins only whitesp
3f70: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 ace and/or .** S
3f80: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 QL comments, the
3f90: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 n no SQL stateme
3fa0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 nts are evaluate
3fb0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 d and the databa
3fc0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 se.** is not cha
3fd0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 nged..**.** Rest
3fe0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 rictions:.**.**
3ff0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 <ul>.** <li> The
4000: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
4010: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 t ensure that th
4020: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 e 1st parameter
4030: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
4040: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 ).** is a v
4050: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 alid and open [d
4060: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
4070: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 on]..** <li> The
4080: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
4090: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 t not close the
40a0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
40b0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 tion] specified
40c0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 by.** the 1
40d0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
40e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 sqlite3_exec() w
40f0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 hile sqlite3_exe
4100: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a c() is running..
4110: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c ** <li> The appl
4120: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ication must not
4130: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 modify the SQL
4140: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 statement text p
4150: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 assed into.**
4160: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d the 2nd param
4170: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f eter of sqlite3_
4180: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c exec() while sql
4190: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 ite3_exec() is r
41a0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e unning..** </ul>
41b0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
41c0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a exec(. sqlite3*
41d0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41f0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 /* An open da
4200: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 tabase */. cons
4210: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 t char *sql,
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4230: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f /* SQL to
4240: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
4250: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 . int (*callbac
4260: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
4270: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a r**,char**), /*
4280: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 Callback functi
4290: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 on */. void *,
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
42c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 /* 1st argume
42d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a nt to callback *
42e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 /. char **errms
42f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 g
4300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
4310: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
4320: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a ten here */.);..
4330: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
4340: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 Result Codes.**
4350: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c KEYWORDS: {resul
4360: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f t code definitio
4370: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 ns}.**.** Many S
4380: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 QLite functions
4390: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 return an intege
43a0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 r result code fr
43b0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e om the set shown
43c0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 .** here in orde
43d0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 r to indicate su
43e0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 ccess or failure
43f0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f ..**.** New erro
4400: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 r codes may be a
4410: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 dded in future v
4420: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
4430: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 e..**.** See als
4440: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 o: [extended res
4450: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 ult code definit
4460: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 ions].*/.#define
4470: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 SQLITE_OK
4480: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 0 /* Succ
4490: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f essful result */
44a0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 ./* beginning-of
44b0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a -error-codes */.
44c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 #define SQLITE_E
44d0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 RROR 1
44e0: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72 /* Generic error
44f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4500: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 TE_INTERNAL
4510: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 2 /* Internal
4520: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 logic error in S
4530: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 QLite */.#define
4540: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 SQLITE_PERM
4550: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 3 /* Acce
4560: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 ss permission de
4570: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nied */.#define
4580: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 SQLITE_ABORT
4590: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 4 /* Callb
45a0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 ack routine requ
45b0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a ested an abort *
45c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
45d0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 _BUSY 5
45e0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 /* The databas
45f0: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 e file is locked
4600: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4610: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 TE_LOCKED
4620: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6 /* A table i
4630: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 n the database i
4640: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 s locked */.#def
4650: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d ine SQLITE_NOMEM
4660: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 7 /* A
4670: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 malloc() failed
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4690: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 TE_READONLY
46a0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 8 /* Attempt t
46b0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e o write a readon
46c0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 ly database */.#
46d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
46e0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f TERRUPT 9 /
46f0: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d * Operation term
4700: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 inated by sqlite
4710: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 3_interrupt()*/.
4720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4730: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 OERR 10
4740: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 /* Some kind of
4750: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f disk I/O error o
4760: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 ccurred */.#defi
4770: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 ne SQLITE_CORRUP
4780: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 T 11 /* Th
4790: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 e database disk
47a0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d image is malform
47b0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
47c0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 LITE_NOTFOUND
47d0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 12 /* Unknown
47e0: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 opcode in sqlit
47f0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
4800: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
4810: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 ITE_FULL
4820: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 13 /* Insertio
4830: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 n failed because
4840: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c database is ful
4850: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
4860: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 ITE_CANTOPEN
4870: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 14 /* Unable t
4880: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 o open the datab
4890: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 ase file */.#def
48a0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f ine SQLITE_PROTO
48b0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 COL 15 /* D
48c0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f atabase lock pro
48d0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 tocol error */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d define SQLITE_EM
48f0: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f PTY 16 /
4900: 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a 23 64 * Not used */.#d
4910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 efine SQLITE_SCH
4920: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a EMA 17 /*
4930: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 The database sc
4940: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a hema changed */.
4950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
4960: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 OOBIG 18
4970: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f /* String or BLO
4980: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c B exceeds size l
4990: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 imit */.#define
49a0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
49b0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 T 19 /* Abort
49c0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 due to constrai
49d0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a nt violation */.
49e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
49f0: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 ISMATCH 20
4a00: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 /* Data type mis
4a10: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 match */.#define
4a20: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 SQLITE_MISUSE
4a30: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 21 /* Libr
4a40: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 ary used incorre
4a50: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ctly */.#define
4a60: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 SQLITE_NOLFS
4a70: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 22 /* Uses
4a80: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 OS features not
4a90: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 supported on hos
4aa0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
4ab0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 ITE_AUTH
4ac0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 23 /* Authoriz
4ad0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a ation denied */.
4ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
4af0: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 ORMAT 24
4b00: 2f 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a 23 /* Not used */.#
4b10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 define SQLITE_RA
4b20: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f NGE 25 /
4b30: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 * 2nd parameter
4b40: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 to sqlite3_bind
4b50: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a out of range */.
4b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
4b70: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 OTADB 26
4b80: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 /* File opened t
4b90: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 hat is not a dat
4ba0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 abase file */.#d
4bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 efine SQLITE_NOT
4bc0: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a ICE 27 /*
4bd0: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 Notifications f
4be0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 rom sqlite3_log(
4bf0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
4c00: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 ITE_WARNING
4c10: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 28 /* Warnings
4c20: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f from sqlite3_lo
4c30: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 g() */.#define S
4c40: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 QLITE_ROW
4c50: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 100 /* sqlite
4c60: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 3_step() has ano
4c70: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a ther row ready *
4c80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4c90: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 _DONE 101
4ca0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 /* sqlite3_ste
4cb0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 p() has finished
4cc0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a executing */./*
4cd0: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f end-of-error-co
4ce0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 des */../*.** CA
4cf0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 PI3REF: Extended
4d00: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a Result Codes.**
4d10: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 KEYWORDS: {exte
4d20: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
4d30: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a definitions}.**
4d40: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 .** In its defau
4d50: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e lt configuration
4d60: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 , SQLite API rou
4d70: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 tines return one
4d80: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a of 30 integer.*
4d90: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d * [result codes]
4da0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 . However, expe
4db0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e rience has shown
4dc0: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a that many of.**
4dd0: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f these result co
4de0: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 des are too coar
4df0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 se-grained. The
4e00: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 y do not provide
4e10: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f as.** much info
4e20: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 rmation about pr
4e30: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 oblems as progra
4e40: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 mmers might like
4e50: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 . In an effort
4e60: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 to.** address th
4e70: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f is, newer versio
4e80: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 ns of SQLite (ve
4e90: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61 74 rsion 3.3.8 [dat
4ea0: 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e eof:3.3.8].** an
4eb0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 d later) include
4ec0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 .** support for
4ed0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c additional resul
4ee0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f t codes that pro
4ef0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c vide more detail
4f00: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a ed information.*
4f10: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 * about errors.
4f20: 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20 These [extended
4f30: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 result codes] ar
4f40: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 e enabled or dis
4f50: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 abled.** on a pe
4f60: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 r database conne
4f70: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e ction basis usin
4f80: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
4f90: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 3_extended_resul
4fa0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 t_codes()] API.
4fb0: 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65 Or, the extende
4fc0: 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 d code for.** th
4fd0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 e most recent er
4fe0: 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69 ror can be obtai
4ff0: 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ned using.** [sq
5000: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 lite3_extended_e
5010: 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 rrcode()]..*/.#d
5020: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5030: 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 RR_READ
5040: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5050: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 RR | (1<<8)).#de
5060: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
5070: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 R_SHORT_READ
5080: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
5090: 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 R | (2<<8)).#def
50a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
50b0: 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 _WRITE
50c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
50d0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 | (3<<8)).#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
50f0: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 FSYNC
5100: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5110: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (4<<8)).#defin
5120: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 e SQLITE_IOERR_D
5130: 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 IR_FSYNC
5140: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5150: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (5<<8)).#define
5160: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 SQLITE_IOERR_TR
5170: 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 UNCATE
5180: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5190: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (6<<8)).#define
51a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 SQLITE_IOERR_FST
51b0: 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 AT (
51c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
51d0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 7<<8)).#define S
51e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f QLITE_IOERR_UNLO
51f0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 CK (S
5200: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 QLITE_IOERR | (8
5210: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5220: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 LITE_IOERR_RDLOC
5230: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 K (SQ
5240: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c LITE_IOERR | (9<
5250: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5260: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 ITE_IOERR_DELETE
5270: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5280: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c ITE_IOERR | (10<
5290: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
52a0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 ITE_IOERR_BLOCKE
52b0: 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c D (SQL
52c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c ITE_IOERR | (11<
52d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
52e0: 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 ITE_IOERR_NOMEM
52f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5300: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c ITE_IOERR | (12<
5310: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5320: 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 ITE_IOERR_ACCESS
5330: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5340: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c ITE_IOERR | (13<
5350: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5360: 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 ITE_IOERR_CHECKR
5370: 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c ESERVEDLOCK (SQL
5380: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c ITE_IOERR | (14<
5390: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
53a0: 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 ITE_IOERR_LOCK
53b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
53c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c ITE_IOERR | (15<
53d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
53e0: 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 ITE_IOERR_CLOSE
53f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5400: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c ITE_IOERR | (16<
5410: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5420: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c ITE_IOERR_DIR_CL
5430: 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c OSE (SQL
5440: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c ITE_IOERR | (17<
5450: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5460: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 ITE_IOERR_SHMOPE
5470: 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c N (SQL
5480: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c ITE_IOERR | (18<
5490: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
54a0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a ITE_IOERR_SHMSIZ
54b0: 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c E (SQL
54c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c ITE_IOERR | (19<
54d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
54e0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 ITE_IOERR_SHMLOC
54f0: 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c K (SQL
5500: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c ITE_IOERR | (20<
5510: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5520: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 ITE_IOERR_SHMMAP
5530: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5540: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c ITE_IOERR | (21<
5550: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5560: 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 ITE_IOERR_SEEK
5570: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5580: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c ITE_IOERR | (22<
5590: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
55a0: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 ITE_IOERR_DELETE
55b0: 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c _NOENT (SQL
55c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c ITE_IOERR | (23<
55d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
55e0: 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 ITE_IOERR_MMAP
55f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5600: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c ITE_IOERR | (24<
5610: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5620: 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d ITE_IOERR_GETTEM
5630: 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c PPATH (SQL
5640: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c ITE_IOERR | (25<
5650: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5660: 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 ITE_IOERR_CONVPA
5670: 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51 4c TH (SQL
5680: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c ITE_IOERR | (26<
5690: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
56a0: 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 ITE_IOERR_VNODE
56b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
56c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c ITE_IOERR | (27<
56d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
56e0: 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 ITE_IOERR_AUTH
56f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5700: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c ITE_IOERR | (28<
5710: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5720: 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 ITE_LOCKED_SHARE
5730: 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c DCACHE (SQL
5740: 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 ITE_LOCKED | (1
5750: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5760: 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 LITE_BUSY_RECOVE
5770: 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 RY (SQ
5780: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 LITE_BUSY | (
5790: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
57a0: 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 QLITE_BUSY_SNAPS
57b0: 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53 HOT (S
57c0: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 QLITE_BUSY |
57d0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (2<<8)).#define
57e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f SQLITE_CANTOPEN_
57f0: 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 NOTEMPDIR (
5800: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 SQLITE_CANTOPEN
5810: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
5820: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 e SQLITE_CANTOPE
5830: 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20 N_ISDIR
5840: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 (SQLITE_CANTOPE
5850: 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 N | (2<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
5870: 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 PEN_FULLPATH
5880: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f (SQLITE_CANTO
5890: 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 PEN | (3<<8)).#d
58a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e efine SQLITE_CAN
58b0: 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 TOPEN_CONVPATH
58c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e (SQLITE_CAN
58d0: 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a TOPEN | (4<<8)).
58e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
58f0: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 ORRUPT_VTAB
5900: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
5910: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 ORRUPT | (1<<8))
5920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5930: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 READONLY_RECOVER
5940: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f Y (SQLITE_
5950: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 READONLY | (1<<8
5960: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5970: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c E_READONLY_CANTL
5980: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 OCK (SQLIT
5990: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c E_READONLY | (2<
59a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
59b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c ITE_READONLY_ROL
59c0: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c LBACK (SQL
59d0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 ITE_READONLY | (
59e0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 3<<8)).#define S
59f0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 QLITE_READONLY_D
5a00: 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 BMOVED (S
5a10: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c QLITE_READONLY |
5a20: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (4<<8)).#define
5a30: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f SQLITE_ABORT_RO
5a40: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 LLBACK
5a50: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 (SQLITE_ABORT |
5a60: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (2<<8)).#define
5a70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5a80: 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 T_CHECK (
5a90: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5aa0: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 T | (1<<8)).#def
5ab0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5ac0: 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b RAINT_COMMITHOOK
5ad0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
5ae0: 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a RAINT | (2<<8)).
5af0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5b00: 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 ONSTRAINT_FOREIG
5b10: 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 NKEY (SQLITE_C
5b20: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c ONSTRAINT | (3<<
5b30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5b40: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 TE_CONSTRAINT_FU
5b50: 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 NCTION (SQLI
5b60: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
5b70: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (4<<8)).#define
5b80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5b90: 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 T_NOTNULL (
5ba0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5bb0: 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 T | (5<<8)).#def
5bc0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5bd0: 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 RAINT_PRIMARYKEY
5be0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
5bf0: 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a RAINT | (6<<8)).
5c00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5c10: 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 ONSTRAINT_TRIGGE
5c20: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 R (SQLITE_C
5c30: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c ONSTRAINT | (7<<
5c40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5c50: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e TE_CONSTRAINT_UN
5c60: 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 IQUE (SQLI
5c70: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
5c80: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (8<<8)).#define
5c90: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5ca0: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28 T_VTAB (
5cb0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5cc0: 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 T | (9<<8)).#def
5cd0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5ce0: 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 RAINT_ROWID
5cf0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
5d00: 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a RAINT |(10<<8)).
5d10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
5d20: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 OTICE_RECOVER_WA
5d30: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e L (SQLITE_N
5d40: 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a OTICE | (1<<8)).
5d50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
5d60: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f OTICE_RECOVER_RO
5d70: 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e LLBACK (SQLITE_N
5d80: 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a OTICE | (2<<8)).
5d90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 #define SQLITE_W
5da0: 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 ARNING_AUTOINDEX
5db0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 (SQLITE_W
5dc0: 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 ARNING | (1<<8))
5dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5de0: 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 AUTH_USER
5df0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5e00: 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 AUTH | (1<<8)).#
5e10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b define SQLITE_OK
5e20: 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c _LOAD_PERMANENTL
5e30: 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b Y (SQLITE_OK
5e40: 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a | (1<<8))../*.*
5e50: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 * CAPI3REF: Flag
5e60: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 s For File Open
5e70: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a Operations.**.**
5e80: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 These bit value
5e90: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 s are intended f
5ea0: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a or use in the.**
5eb0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
5ec0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f o the [sqlite3_o
5ed0: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 pen_v2()] interf
5ee0: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 ace and.** in th
5ef0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
5f00: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
5f10: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f vfs.xOpen] metho
5f20: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 d..*/.#define SQ
5f30: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
5f40: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 LY 0x000
5f50: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 00001 /* Ok for
5f60: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
5f70: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
5f80: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
5f90: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 ITE 0x000
5fa0: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 00002 /* Ok for
5fb0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
5fc0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
5fd0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
5fe0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
5ff0: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 00004 /* Ok for
6000: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
6010: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
6020: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
6030: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 ONCLOSE 0x000
6040: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 00008 /* VFS on
6050: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
6060: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 LITE_OPEN_EXCLUS
6070: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 IVE 0x000
6080: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 00010 /* VFS on
6090: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
60a0: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 LITE_OPEN_AUTOPR
60b0: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 OXY 0x000
60c0: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 00020 /* VFS on
60d0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
60e0: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 LITE_OPEN_URI
60f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6100: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 00040 /* Ok for
6110: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
6120: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
6130: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 LITE_OPEN_MEMORY
6140: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6150: 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 00080 /* Ok for
6160: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
6170: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
6180: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 LITE_OPEN_MAIN_D
6190: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 B 0x000
61a0: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 00100 /* VFS on
61b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
61c0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 LITE_OPEN_TEMP_D
61d0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 B 0x000
61e0: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 00200 /* VFS on
61f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
6200: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 LITE_OPEN_TRANSI
6210: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 ENT_DB 0x000
6220: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 00400 /* VFS on
6230: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
6240: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a LITE_OPEN_MAIN_J
6250: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 OURNAL 0x000
6260: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 00800 /* VFS on
6270: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
6280: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a LITE_OPEN_TEMP_J
6290: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 OURNAL 0x000
62a0: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 01000 /* VFS on
62b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
62c0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 LITE_OPEN_SUBJOU
62d0: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 RNAL 0x000
62e0: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 02000 /* VFS on
62f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
6300: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 LITE_OPEN_MASTER
6310: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 _JOURNAL 0x000
6320: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 04000 /* VFS on
6330: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
6340: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
6350: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 X 0x000
6360: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 08000 /* Ok for
6370: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
6380: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
6390: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 LITE_OPEN_FULLMU
63a0: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 TEX 0x000
63b0: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 10000 /* Ok for
63c0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
63d0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
63e0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
63f0: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 CACHE 0x000
6400: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20000 /* Ok for
6410: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
6420: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
6430: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 LITE_OPEN_PRIVAT
6440: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 ECACHE 0x000
6450: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 40000 /* Ok for
6460: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
6470: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
6480: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 LITE_OPEN_WAL
6490: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
64a0: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 80000 /* VFS on
64b0: 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 ly */../* Reserv
64c0: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 ed:
64d0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
64e0: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a F00000 */../*.**
64f0: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 CAPI3REF: Devic
6500: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 e Characteristic
6510: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 s.**.** The xDev
6520: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
6530: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 cs method of the
6540: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
6550: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 hods].** object
6560: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 returns an integ
6570: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 er which is a ve
6580: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a ctor of these.**
6590: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 bit values expr
65a0: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 essing I/O chara
65b0: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 cteristics of th
65c0: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a e mass storage.*
65d0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f * device that ho
65e0: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 lds the file tha
65f0: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 t the [sqlite3_i
6600: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 o_methods].** re
6610: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 fers to..**.** T
6620: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
6630: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 ATOMIC property
6640: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 means that all w
6650: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 rites of.** any
6660: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e size are atomic.
6670: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
6680: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c AP_ATOMICnnn val
6690: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 ues.** mean that
66a0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b writes of block
66b0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 s that are nnn b
66c0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 ytes in size and
66d0: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 .** are aligned
66e0: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 to an address wh
66f0: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ich is an intege
6700: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a r multiple of.**
6710: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e nnn are atomic.
6720: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
6730: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 AP_SAFE_APPEND v
6740: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 alue means.** th
6750: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 at when data is
6760: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 appended to a fi
6770: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 le, the data is
6780: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 appended.** firs
6790: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 t then the size
67a0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 of the file is e
67b0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 xtended, never t
67c0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 he other.** way
67d0: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c around. The SQL
67e0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e ITE_IOCAP_SEQUEN
67f0: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 TIAL property me
6800: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f ans that.** info
6810: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 rmation is writt
6820: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 en to disk in th
6830: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 e same order as
6840: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 calls.** to xWri
6850: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 te(). The SQLIT
6860: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 E_IOCAP_POWERSAF
6870: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 E_OVERWRITE prop
6880: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a erty means that.
6890: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 ** after reboot
68a0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 following a cras
68b0: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c h or power loss,
68c0: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 the only bytes
68d0: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 in a.** file tha
68e0: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 t were written a
68f0: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f t the applicatio
6900: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 n level might ha
6910: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e ve changed.** an
6920: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 d that adjacent
6930: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 bytes, even byte
6940: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d s within the sam
6950: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 e sector are.**
6960: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 guaranteed to be
6970: 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 unchanged. The
6980: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e SQLITE_IOCAP_UN
6990: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f DELETABLE_WHEN_O
69a0: 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 PEN.** flag indi
69b0: 63 61 74 65 73 20 74 68 61 74 20 61 20 66 69 6c cates that a fil
69c0: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 e cannot be dele
69d0: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 ted when open.
69e0: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f The.** SQLITE_IO
69f0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c CAP_IMMUTABLE fl
6a00: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 ag indicates tha
6a10: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e t the file is on
6a20: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 .** read-only me
6a30: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 dia and cannot b
6a40: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 e changed even b
6a50: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 y processes with
6a60: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 .** elevated pri
6a70: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 vileges..*/.#def
6a80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
6a90: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 _ATOMIC
6aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
6ab0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 01.#define SQLIT
6ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 E_IOCAP_ATOMIC51
6ad0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 2 0
6ae0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e x00000002.#defin
6af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6b00: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 TOMIC1K
6b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
6b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 IOCAP_ATOMIC2K
6b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6b50: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 0000008.#define
6b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6b70: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 MIC4K
6b80: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 0x00000010.#
6b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6ba0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 CAP_ATOMIC8K
6bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6bc0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 00020.#define SQ
6bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6be0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 C16K
6bf0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 0x00000040.#de
6c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6c10: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 P_ATOMIC32K
6c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6c30: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 080.#define SQLI
6c40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 TE_IOCAP_ATOMIC6
6c50: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 4K
6c60: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 0x00000100.#defi
6c70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6c80: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 SAFE_APPEND
6c90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 0x0000020
6ca0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
6cb0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
6cc0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 L 0x
6cd0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 00000400.#define
6ce0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e SQLITE_IOCAP_UN
6cf0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f DELETABLE_WHEN_O
6d00: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a PEN 0x00000800.
6d10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6d20: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f OCAP_POWERSAFE_O
6d30: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 VERWRITE 0x00
6d40: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 001000.#define S
6d50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 QLITE_IOCAP_IMMU
6d60: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 TABLE
6d70: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 0x00002000../
6d80: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
6d90: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 ile Locking Leve
6da0: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 ls.**.** SQLite
6db0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 uses one of thes
6dc0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
6dd0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a as the second.*
6de0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 * argument to ca
6df0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 lls it makes to
6e00: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 the xLock() and
6e10: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 xUnlock() method
6e20: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 s.** of an [sqli
6e30: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
6e40: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 object..*/.#defi
6e50: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e ne SQLITE_LOCK_N
6e60: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 ONE 0.#
6e70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
6e80: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 CK_SHARED
6e90: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
6ea0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 E_LOCK_RESERVED
6eb0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
6ec0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
6ed0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 NG 3.#defi
6ee0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 ne SQLITE_LOCK_E
6ef0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a XCLUSIVE 4..
6f00: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
6f10: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 Synchronization
6f20: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a Type Flags.**.**
6f30: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 When SQLite inv
6f40: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 okes the xSync()
6f50: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a method of an.**
6f60: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
6f70: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 hods] object it
6f80: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 uses a combinati
6f90: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 on of.** these i
6fa0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 nteger values as
6fb0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
6fc0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e ment..**.** When
6fd0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 the SQLITE_SYNC
6fe0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 _DATAONLY flag i
6ff0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 s used, it means
7000: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e that the.** syn
7010: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 c operation only
7020: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 needs to flush
7030: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f data to mass sto
7040: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 rage. Inode.**
7050: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 information need
7060: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e not be flushed.
7070: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f If the lower fo
7080: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 ur bits of the f
7090: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c lag.** equal SQL
70a0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c ITE_SYNC_NORMAL,
70b0: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 that means to u
70c0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 se normal fsync(
70d0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 ) semantics..**
70e0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 If the lower fou
70f0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c r bits equal SQL
7100: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 ITE_SYNC_FULL, t
7110: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 hat means.** to
7120: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 use Mac OS X sty
7130: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 le fullsync inst
7140: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a ead of fsync()..
7150: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e **.** Do not con
7160: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f fuse the SQLITE_
7170: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 SYNC_NORMAL and
7180: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
7190: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 flags.** with t
71a0: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 he [PRAGMA synch
71b0: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 ronous]=NORMAL a
71c0: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 nd [PRAGMA synch
71d0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 ronous]=FULL.**
71e0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b settings. The [
71f0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 synchronous prag
7200: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 ma] determines w
7210: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 hen calls to the
7220: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 .** xSync VFS me
7230: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 thod occur and a
7240: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 pplies uniformly
7250: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 across all plat
7260: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 forms..** The SQ
7270: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
7280: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 and SQLITE_SYNC
7290: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 _FULL flags dete
72a0: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 rmine how.** ene
72b0: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f rgetic or rigoro
72c0: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 us or forceful t
72d0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f he sync operatio
72e0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e ns are and.** on
72f0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 ly make a differ
7300: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 ence on Mac OSX
7310: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 for the default
7320: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 SQLite code..**
7330: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 (Third-party VFS
7340: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
7350: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 might also make
7360: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e the distinction
7370: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 .** between SQLI
7380: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 TE_SYNC_NORMAL a
7390: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 nd SQLITE_SYNC_F
73a0: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 ULL, but among t
73b0: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 he.** operating
73c0: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 systems natively
73d0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 supported by SQ
73e0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f Lite, only Mac O
73f0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 SX.** cares abou
7400: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 t the difference
7410: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 .).*/.#define SQ
7420: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
7430: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 0x00002.
7440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
7450: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 YNC_FULL
7460: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 0x00003.#defin
7470: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
7480: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 TAONLY 0x00
7490: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 010../*.** CAPI3
74a0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
74b0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 e Open File Hand
74c0: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c le.**.** An [sql
74d0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
74e0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 t represents an
74f0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 open file in the
7500: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 .** [sqlite3_vf
7510: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 s | OS interface
7520: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 layer]. Indivi
7530: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 dual OS interfac
7540: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
7550: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e ions will.** wan
7560: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 t to subclass th
7570: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 is object by app
7580: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 ending additiona
7590: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 l fields.** for
75a0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 their own use.
75b0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 The pMethods ent
75c0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ry is a pointer
75d0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 to an.** [sqlite
75e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
75f0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 ject that define
7600: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 s methods for pe
7610: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 rforming.** I/O
7620: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 operations on th
7630: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a e open file..*/.
7640: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
7650: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 qlite3_file sqli
7660: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 te3_file;.struct
7670: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a sqlite3_file {.
7680: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 const struct s
7690: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
76a0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a s *pMethods; /*
76b0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 Methods for an
76c0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a open file */.};.
76d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
76e0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 OS Interface Fi
76f0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f le Virtual Metho
7700: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 ds Object.**.**
7710: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 Every file opene
7720: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
7730: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 3_vfs.xOpen] met
7740: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e hod populates an
7750: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
7760: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d e] object (or, m
7770: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 ore commonly, a
7780: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a subclass of the.
7790: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
77a0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 ] object) with a
77b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
77c0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
77d0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 object..** This
77e0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
77f0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 he methods used
7800: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f to perform vario
7810: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a us operations.**
7820: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 against the ope
7830: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 n file represent
7840: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 ed by the [sqlit
7850: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e e3_file] object.
7860: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 .**.** If the [s
7870: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
7880: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 ] method sets th
7890: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 e sqlite3_file.p
78a0: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 Methods element
78b0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c .** to a non-NUL
78c0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 L pointer, then
78d0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d the sqlite3_io_m
78e0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 ethods.xClose me
78f0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 thod.** may be i
7900: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 nvoked even if t
7910: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
7920: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 xOpen] reported
7930: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 that it failed.
7940: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 The.** only way
7950: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 to prevent a ca
7960: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c ll to xClose fol
7970: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 lowing a failed
7980: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
7990: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 en].** is for th
79a0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
79b0: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 Open] to set the
79c0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d sqlite3_file.pM
79d0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a ethods element.*
79e0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a * to NULL..**.**
79f0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d The flags argum
7a00: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 ent to xSync may
7a10: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 be one of [SQLI
7a20: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 TE_SYNC_NORMAL]
7a30: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 or.** [SQLITE_SY
7a40: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 NC_FULL]. The f
7a50: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 irst choice is t
7a60: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 he normal fsync(
7a70: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 )..** The second
7a80: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 choice is a Mac
7a90: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c OS X style full
7aa0: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 sync. The [SQLI
7ab0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
7ac0: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 ].** flag may be
7ad0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 ORed in to indi
7ae0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 cate that only t
7af0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 he data of the f
7b00: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 ile.** and not i
7b10: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 ts inode needs t
7b20: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a o be synced..**.
7b30: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 ** The integer v
7b40: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 alues to xLock()
7b50: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 and xUnlock() a
7b60: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c re one of.** <ul
7b70: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
7b80: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a E_LOCK_NONE],.**
7b90: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
7ba0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c CK_SHARED],.** <
7bb0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
7bc0: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c _RESERVED],.** <
7bd0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
7be0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a _PENDING], or.**
7bf0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
7c00: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a CK_EXCLUSIVE]..*
7c10: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b * </ul>.** xLock
7c20: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 () increases the
7c30: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 lock. xUnlock()
7c40: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c decreases the l
7c50: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 ock..** The xChe
7c60: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 ckReservedLock()
7c70: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 method checks w
7c80: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 hether any datab
7c90: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a ase connection,.
7ca0: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 ** either in thi
7cb0: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 s process or in
7cc0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 some other proce
7cd0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 ss, is holding a
7ce0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 RESERVED,.** PE
7cf0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 NDING, or EXCLUS
7d00: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 IVE lock on the
7d10: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e file. It return
7d20: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 s true.** if suc
7d30: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 h a lock exists
7d40: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 and false otherw
7d50: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ise..**.** The x
7d60: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 FileControl() me
7d70: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 thod is a generi
7d80: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 c interface that
7d90: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a allows custom.*
7da0: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 * VFS implementa
7db0: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c tions to directl
7dc0: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 y control an ope
7dd0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 n file using the
7de0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
7df0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 e_control()] int
7e00: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 erface. The sec
7e10: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e ond "op" argumen
7e20: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 t is an.** integ
7e30: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 er opcode. The
7e40: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
7e50: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e s a generic poin
7e60: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a ter intended to.
7e70: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 ** point to a st
7e80: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 ructure that may
7e90: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e contain argumen
7ea0: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 ts or space in w
7eb0: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 hich to.** write
7ec0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 return values.
7ed0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 Potential uses
7ee0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c for xFileControl
7ef0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 () might be.** f
7f00: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 unctions to enab
7f10: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b le blocking lock
7f20: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c s with timeouts,
7f30: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a to change the.*
7f40: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 * locking strate
7f50: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 gy (for example
7f60: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 to use dot-file
7f70: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 locks), to inqui
7f80: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 re.** about the
7f90: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b status of a lock
7fa0: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 , or to break st
7fb0: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 ale locks. The
7fc0: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 SQLite.** core r
7fd0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f eserves all opco
7fe0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 des less than 10
7ff0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 0 for its own us
8000: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f e..** A [file co
8010: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 ntrol opcodes |
8020: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d list of opcodes]
8030: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 less than 100 i
8040: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 s available..**
8050: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
8060: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f t define a custo
8070: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d m xFileControl m
8080: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 ethod should use
8090: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 opcodes.** grea
80a0: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 ter than 100 to
80b0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e avoid conflicts.
80c0: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 VFS implementa
80d0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 tions should.**
80e0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e return [SQLITE_N
80f0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c OTFOUND] for fil
8100: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 e control opcode
8110: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e s that they do n
8120: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e ot.** recognize.
8130: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 .**.** The xSect
8140: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 orSize() method
8150: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 returns the sect
8160: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a or size of the.*
8170: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e * device that un
8180: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 derlies the file
8190: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 . The sector si
81a0: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e ze is the.** min
81b0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 imum write that
81c0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 can be performed
81d0: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 without disturb
81e0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 ing.** other byt
81f0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 es in the file.
8200: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 The xDeviceChar
8210: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a acteristics().**
8220: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
8230: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 a bit vector des
8240: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 cribing behavior
8250: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 s of the.** unde
8260: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a rlying device:.*
8270: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
8280: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
8290: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 ATOMIC].** <li>
82a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
82b0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e OMIC512].** <li>
82c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
82d0: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC1K].** <li>
82e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
82f0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC2K].** <li>
8300: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
8310: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC4K].** <li>
8320: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
8330: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC8K].** <li>
8340: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
8350: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 TOMIC16K].** <li
8360: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
8370: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c ATOMIC32K].** <l
8380: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
8390: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c _ATOMIC64K].** <
83a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
83b0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a P_SAFE_APPEND].*
83c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
83d0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d OCAP_SEQUENTIAL]
83e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
83f0: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 _IOCAP_UNDELETAB
8400: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a LE_WHEN_OPEN].**
8410: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
8420: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 CAP_POWERSAFE_OV
8430: 45 52 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e ERWRITE].** <li>
8440: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 [SQLITE_IOCAP_I
8450: 4d 4d 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 2f 75 MMUTABLE].** </u
8460: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c l>.**.** The SQL
8470: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
8480: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 property means
8490: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 that all writes
84a0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 of.** any size a
84b0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 re atomic. The
84c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
84d0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a MICnnn values.**
84e0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 mean that write
84f0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 s of blocks that
8500: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 are nnn bytes i
8510: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 n size and.** ar
8520: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
8530: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 address which is
8540: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 an integer mult
8550: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 iple of.** nnn a
8560: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 re atomic. The
8570: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 SQLITE_IOCAP_SAF
8580: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d E_APPEND value m
8590: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 eans.** that whe
85a0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 n data is append
85b0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 ed to a file, th
85c0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 e data is append
85d0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e ed.** first then
85e0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
85f0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 file is extende
8600: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 d, never the oth
8610: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 er.** way around
8620: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
8630: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 CAP_SEQUENTIAL p
8640: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
8650: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f at.** informatio
8660: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 n is written to
8670: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 disk in the same
8680: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a order as calls.
8690: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a ** to xWrite()..
86a0: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 **.** If xRead()
86b0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
86c0: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 IOERR_SHORT_READ
86d0: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 it must also fi
86e0: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 ll.** in the unr
86f0: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 ead portions of
8700: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 the buffer with
8710: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 zeros. A VFS th
8720: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a at.** fails to z
8730: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 ero-fill short r
8740: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 eads might seem
8750: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 to work. Howeve
8760: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f r,.** failure to
8770: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 zero-fill short
8780: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e reads will even
8790: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a tually lead to.*
87a0: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 * database corru
87b0: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 ption..*/.typede
87c0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
87d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 _io_methods sqli
87e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a te3_io_methods;.
87f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
8800: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e o_methods {. in
8810: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e t iVersion;. in
8820: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 t (*xClose)(sqli
8830: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e te3_file*);. in
8840: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 t (*xRead)(sqlit
8850: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c e3_file*, void*,
8860: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 int iAmt, sqlit
8870: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b e3_int64 iOfst);
8880: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 . int (*xWrite)
8890: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
88a0: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
88b0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 iAmt, sqlite3_i
88c0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 nt64 iOfst);. i
88d0: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 nt (*xTruncate)(
88e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 sqlite3_file*, s
88f0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a qlite3_int64 siz
8900: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e e);. int (*xSyn
8910: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a c)(sqlite3_file*
8920: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 , int flags);.
8930: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 int (*xFileSize)
8940: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
8950: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 sqlite3_int64 *p
8960: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 Size);. int (*x
8970: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 Lock)(sqlite3_fi
8980: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 le*, int);. int
8990: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 (*xUnlock)(sqli
89a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b te3_file*, int);
89b0: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 . int (*xCheckR
89c0: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c eservedLock)(sql
89d0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
89e0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 *pResOut);. int
89f0: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 (*xFileControl)
8a00: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
8a10: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 int op, void *pA
8a20: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 rg);. int (*xSe
8a30: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 ctorSize)(sqlite
8a40: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 3_file*);. int
8a50: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 (*xDeviceCharact
8a60: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 eristics)(sqlite
8a70: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 3_file*);. /* M
8a80: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
8a90: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 valid for versi
8aa0: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a on 1 */. int (*
8ab0: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 xShmMap)(sqlite3
8ac0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c _file*, int iPg,
8ad0: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 int pgsz, int,
8ae0: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 void volatile**)
8af0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f ;. int (*xShmLo
8b00: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
8b10: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 *, int offset, i
8b20: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 nt n, int flags)
8b30: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 ;. void (*xShmB
8b40: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f arrier)(sqlite3_
8b50: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
8b60: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 xShmUnmap)(sqlit
8b70: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 e3_file*, int de
8b80: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 leteFlag);. /*
8b90: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 Methods above ar
8ba0: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 e valid for vers
8bb0: 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 ion 2 */. int (
8bc0: 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 *xFetch)(sqlite3
8bd0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f _file*, sqlite3_
8be0: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 int64 iOfst, int
8bf0: 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 iAmt, void **pp
8c00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 );. int (*xUnfe
8c10: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c tch)(sqlite3_fil
8c20: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
8c30: 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 4 iOfst, void *p
8c40: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 );. /* Methods
8c50: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 above are valid
8c60: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f for version 3 */
8c70: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c . /* Additional
8c80: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 methods may be
8c90: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
8ca0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a releases */.};..
8cb0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
8cc0: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f Standard File Co
8cd0: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a ntrol Opcodes.**
8ce0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 KEYWORDS: {file
8cf0: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 control opcodes
8d00: 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 } {file control
8d10: 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 opcode}.**.** Th
8d20: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 ese integer cons
8d30: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 tants are opcode
8d40: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 s for the xFileC
8d50: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a ontrol method.**
8d60: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
8d70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
8d80: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 ect and for the
8d90: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
8da0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 ntrol()].** inte
8db0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c rface..**.** <ul
8dc0: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 >.** <li>[[SQLIT
8dd0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
8de0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 E]].** The [SQLI
8df0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
8e00: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 TE] opcode is us
8e10: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 ed for debugging
8e20: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 . This.** opcod
8e30: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 e causes the xFi
8e40: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
8e50: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 to write the cu
8e60: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a rrent state of.*
8e70: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 * the lock (one
8e80: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f of [SQLITE_LOCK_
8e90: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c NONE], [SQLITE_L
8ea0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 OCK_SHARED],.**
8eb0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 [SQLITE_LOCK_RES
8ec0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f ERVED], [SQLITE_
8ed0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f LOCK_PENDING], o
8ee0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 r [SQLITE_LOCK_E
8ef0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e XCLUSIVE]).** in
8f00: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 to an integer th
8f10: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 at the pArg argu
8f20: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 ment points to.
8f30: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a This capability.
8f40: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e ** is used durin
8f50: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 g testing and is
8f60: 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 only available
8f70: 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f when the SQLITE_
8f80: 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d TEST.** compile-
8f90: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 time option is u
8fa0: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b sed..**.** <li>[
8fb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 [SQLITE_FCNTL_SI
8fc0: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 ZE_HINT]].** The
8fd0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 [SQLITE_FCNTL_S
8fe0: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 IZE_HINT] opcode
8ff0: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 is used by SQLi
9000: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 te to give the V
9010: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 FS.** layer a hi
9020: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 nt of how large
9030: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
9040: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 e will grow to b
9050: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 e during the.**
9060: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 current transact
9070: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 ion. This hint
9080: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 is not guarantee
9090: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 d to be accurate
90a0: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 but it.** is of
90b0: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 ten close. The
90c0: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d underlying VFS m
90d0: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 ight choose to p
90e0: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 reallocate datab
90f0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 ase.** file spac
9100: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 e based on this
9110: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f hint in order to
9120: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 help writes to
9130: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
9140: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e file run faster.
9150: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
9160: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f ITE_FCNTL_CHUNK_
9170: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 SIZE]].** The [S
9180: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e QLITE_FCNTL_CHUN
9190: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 K_SIZE] opcode i
91a0: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 s used to reques
91b0: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a t that the VFS.*
91c0: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 * extends and tr
91d0: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 uncates the data
91e0: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 base file in chu
91f0: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 nks of a size sp
9200: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 ecified.** by th
9210: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 e user. The four
9220: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b th argument to [
9230: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
9240: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a trol()] should .
9250: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 ** point to an i
9260: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 nteger (type int
9270: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 ) containing the
9280: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 new chunk-size
9290: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 to use.** for th
92a0: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 e nominated data
92b0: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 base. Allocating
92c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 database file s
92d0: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a pace in large.**
92e0: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 chunks (say 1MB
92f0: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 at a time), may
9300: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 reduce file-sys
9310: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f tem fragmentatio
9320: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 n and.** improve
9330: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 performance on
9340: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a some systems..**
9350: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
9360: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e _FCNTL_FILE_POIN
9370: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 TER]].** The [SQ
9380: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f LITE_FCNTL_FILE_
9390: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 POINTER] opcode
93a0: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 is used to obtai
93b0: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 n a pointer.** t
93c0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 o the [sqlite3_f
93d0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f ile] object asso
93e0: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 ciated with a pa
93f0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 rticular databas
9400: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e e.** connection.
9410: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 See also [SQLI
9420: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c TE_FCNTL_JOURNAL
9430: 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a _POINTER]..**.**
9440: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
9450: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e NTL_JOURNAL_POIN
9460: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 TER]].** The [SQ
9470: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e LITE_FCNTL_JOURN
9480: 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f AL_POINTER] opco
9490: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 de is used to ob
94a0: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a tain a pointer.*
94b0: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 * to the [sqlite
94c0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 3_file] object a
94d0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
94e0: 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 he journal file
94f0: 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b (either.** the [
9500: 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c rollback journal
9510: 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d ] or the [write-
9520: 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 ahead log]) for
9530: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 a particular dat
9540: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
9550: 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b ion. See also [
9560: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c SQLITE_FCNTL_FIL
9570: 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a E_POINTER]..**.*
9580: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
9590: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 CNTL_SYNC_OMITTE
95a0: 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 D]].** No longer
95b0: 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c in use..**.** <
95c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
95d0: 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 L_SYNC]].** The
95e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 [SQLITE_FCNTL_SY
95f0: 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 NC] opcode is ge
9600: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c nerated internal
9610: 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 ly by SQLite and
9620: 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 .** sent to the
9630: 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 VFS immediately
9640: 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 before the xSync
9650: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b method is invok
9660: 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 ed on a.** datab
9670: 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 ase file descrip
9680: 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 tor. Or, if the
9690: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 xSync method is
96a0: 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 not invoked .**
96b0: 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72 because the user
96c0: 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 has configured
96d0: 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 SQLite with .**
96e0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e [PRAGMA synchron
96f0: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e ous | PRAGMA syn
9700: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 chronous=OFF] it
9710: 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 is invoked in p
9720: 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 lace .** of the
9730: 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e xSync method. In
9740: 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 most cases, the
9750: 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e pointer argumen
9760: 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a t passed with.**
9770: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 this file-contr
9780: 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 ol is NULL. Howe
9790: 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 ver, if the data
97a0: 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 base file is bei
97b0: 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 ng synced.** as
97c0: 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d part of a multi-
97d0: 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c database commit,
97e0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f the argument po
97f0: 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 ints to a nul-te
9800: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 rminated.** stri
9810: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 ng containing th
9820: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d e transactions m
9830: 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 aster-journal fi
9840: 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 le name. VFSes t
9850: 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e hat .** do not n
9860: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 eed this signal
9870: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 should silently
9880: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f ignore this opco
9890: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 de. Applications
98a0: 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 .** should not
98b0: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 call [sqlite3_fi
98c0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 le_control()] wi
98d0: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 th this opcode a
98e0: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a s doing so may .
98f0: 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f ** disrupt the o
9900: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 peration of the
9910: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 specialized VFSe
9920: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 s that do requir
9930: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c e it. .**.** <l
9940: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
9950: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f _COMMIT_PHASETWO
9960: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
9970: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 E_FCNTL_COMMIT_P
9980: 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 HASETWO] opcode
9990: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 is generated int
99a0: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 ernally by SQLit
99b0: 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f e.** and sent to
99c0: 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61 the VFS after a
99d0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 transaction has
99e0: 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 been committed
99f0: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 immediately.** b
9a00: 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 ut before the da
9a10: 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b tabase is unlock
9a20: 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 ed. VFSes that d
9a30: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 o not need this
9a40: 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 signal.** should
9a50: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 silently ignore
9a60: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 this opcode. Ap
9a70: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c plications shoul
9a80: 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 d not call.** [s
9a90: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
9aa0: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 rol()] with this
9ab0: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 opcode as doing
9ac0: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 so may disrupt
9ad0: 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f the .** operatio
9ae0: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c n of the special
9af0: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20 ized VFSes that
9b00: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 do require it.
9b10: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
9b20: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
9b30: 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 AV_RETRY]].** ^T
9b40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
9b50: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d _WIN32_AV_RETRY]
9b60: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
9b70: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 to configure aut
9b80: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 omatic.** retry
9b90: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 counts and inter
9ba0: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e vals for certain
9bb0: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 disk I/O operat
9bc0: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 ions for the.**
9bd0: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e windows [VFS] in
9be0: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 order to provid
9bf0: 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 e robustness in
9c00: 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a the presence of.
9c10: 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 ** anti-virus pr
9c20: 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 ograms. By defa
9c30: 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 ult, the windows
9c40: 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 VFS will retry
9c50: 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 file read,.** fi
9c60: 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 le write, and fi
9c70: 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 le delete operat
9c80: 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 ions up to 10 ti
9c90: 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 mes, with a dela
9ca0: 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 y.** of 25 milli
9cb0: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 seconds before t
9cc0: 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 he first retry a
9cd0: 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 nd with the dela
9ce0: 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 y increasing.**
9cf0: 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c by an additional
9d00: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 25 milliseconds
9d10: 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 with each subse
9d20: 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 quent retry. Th
9d30: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c is.** opcode all
9d40: 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 ows these two va
9d50: 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 lues (10 retries
9d60: 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 and 25 millisec
9d70: 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a onds of delay).*
9d80: 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 * to be adjusted
9d90: 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 . The values ar
9da0: 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c e changed for al
9db0: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 l database conne
9dc0: 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e ctions.** within
9dd0: 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 the same proces
9de0: 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 s. The argument
9df0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
9e00: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f an array of two
9e10: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 .** integers whe
9e20: 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 re the first int
9e30: 65 67 65 72 20 69 73 20 74 68 65 20 6e 65 77 20 eger is the new
9e40: 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 retry count and
9e50: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e the second.** in
9e60: 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c teger is the del
9e70: 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 ay. If either i
9e80: 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 nteger is negati
9e90: 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 ve, then the set
9ea0: 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 ting.** is not c
9eb0: 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 hanged but inste
9ec0: 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c ad the prior val
9ed0: 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 ue of that setti
9ee0: 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a ng is written.**
9ef0: 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 into the array
9f00: 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 entry, allowing
9f10: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 the current retr
9f20: 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 y settings to be
9f30: 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 .** interrogated
9f40: 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 . The zDbName p
9f50: 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f arameter is igno
9f60: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b red..**.** <li>[
9f70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 [SQLITE_FCNTL_PE
9f80: 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e RSIST_WAL]].** ^
9f90: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
9fa0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f L_PERSIST_WAL] o
9fb0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
9fc0: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 set or query th
9fd0: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 e.** persistent
9fe0: 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 [WAL | Write Ahe
9ff0: 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e ad Log] setting.
a000: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 By default, th
a010: 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 e auxiliary.** w
a020: 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 rite ahead log a
a030: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 nd shared memory
a040: 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 files used for
a050: 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 transaction cont
a060: 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d rol.** are autom
a070: 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 atically deleted
a080: 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 when the latest
a090: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 connection to t
a0a0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 he database.** c
a0b0: 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 loses. Setting
a0c0: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d persistent WAL m
a0d0: 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 ode causes those
a0e0: 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 files to persis
a0f0: 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 t after.** close
a100: 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 . Persisting th
a110: 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 e files is usefu
a120: 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f l when other pro
a130: 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e cesses that do n
a140: 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 ot.** have write
a150: 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 permission on t
a160: 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e he directory con
a170: 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 taining the data
a180: 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a base file want.*
a190: 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 * to read the da
a1a0: 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 tabase file, as
a1b0: 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 the WAL and shar
a1c0: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 ed memory files
a1d0: 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e must exist.** in
a1e0: 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 order for the d
a1f0: 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 atabase to be re
a200: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 adable. The fou
a210: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
a220: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
a230: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 e_control()] for
a240: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f this opcode sho
a250: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 uld be a pointer
a260: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a to an integer..
a270: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 ** That integer
a280: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 is 0 to disable
a290: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d persistent WAL m
a2a0: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 ode or 1 to enab
a2b0: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a le persistent.**
a2c0: 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 WAL mode. If t
a2d0: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 he integer is -1
a2e0: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 , then it is ove
a2f0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 rwritten with th
a300: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c e current.** WAL
a310: 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 persistence set
a320: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e ting..**.** <li>
a330: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [[SQLITE_FCNTL_P
a340: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
a350: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 TE]].** ^The [SQ
a360: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 LITE_FCNTL_POWER
a370: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 SAFE_OVERWRITE]
a380: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
a390: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 o set or query t
a3a0: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 he.** persistent
a3b0: 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 "powersafe-over
a3c0: 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 write" or "PSOW"
a3d0: 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 setting. The P
a3e0: 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 SOW setting.** d
a3f0: 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 etermines the [S
a400: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 QLITE_IOCAP_POWE
a410: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d RSAFE_OVERWRITE]
a420: 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 bit of the.** x
a430: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 DeviceCharacteri
a440: 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 stics methods. T
a450: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
a460: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ter to.** [sqlit
a470: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
a480: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f )] for this opco
a490: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 de should be a p
a4a0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
a4b0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e eger..** That in
a4c0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 teger is 0 to di
a4d0: 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 sable zero-damag
a4e0: 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 e mode or 1 to e
a4f0: 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 nable zero-damag
a500: 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 e.** mode. If t
a510: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 he integer is -1
a520: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 , then it is ove
a530: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 rwritten with th
a540: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 e current.** zer
a550: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 o-damage mode se
a560: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 tting..**.** <li
a570: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
a580: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e OVERWRITE]].** ^
a590: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
a5a0: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 L_OVERWRITE] opc
a5b0: 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 ode is invoked b
a5c0: 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f y SQLite after o
a5d0: 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 pening.** a writ
a5e0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f e transaction to
a5f0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 indicate that,
a600: 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c unless it is rol
a610: 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d led back for som
a620: 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 e.** reason, the
a630: 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 entire database
a640: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 file will be ov
a650: 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 erwritten by the
a660: 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 current .** tra
a670: 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 nsaction. This i
a680: 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d s used by VACUUM
a690: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a operations..**.
a6a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
a6b0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a FCNTL_VFSNAME]].
a6c0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
a6d0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f FCNTL_VFSNAME] o
a6e0: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 pcode can be use
a6f0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 d to obtain the
a700: 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 names of.** all
a710: 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 [VFSes] in the V
a720: 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e FS stack. The n
a730: 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 ames are of all
a740: 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 VFS shims and th
a750: 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f e.** final botto
a760: 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 m-level VFS are
a770: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d written into mem
a780: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ory obtained fro
a790: 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d m .** [sqlite3_m
a7a0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 alloc()] and the
a7b0: 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 result is store
a7c0: 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 d in the char* v
a7d0: 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 ariable.** that
a7e0: 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
a7f0: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 eter of [sqlite3
a800: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
a810: 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 points to..** T
a820: 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 he caller is res
a830: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 ponsible for fre
a840: 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 eing the memory
a850: 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 when done. As w
a860: 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d ith.** all file-
a870: 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c control actions,
a880: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 there is no gua
a890: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 rantee that this
a8a0: 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a will actually.*
a8b0: 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 * do anything.
a8c0: 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 Callers should i
a8d0: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 nitialize the ch
a8e0: 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 ar* variable to
a8f0: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 a NULL.** pointe
a900: 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 r in case this f
a910: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e ile-control is n
a920: 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 ot implemented.
a930: 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 This file-contr
a940: 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 ol.** is intende
a950: 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 d for diagnostic
a960: 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a use only..**.**
a970: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
a980: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d NTL_VFS_POINTER]
a990: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ].** ^The [SQLIT
a9a0: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e E_FCNTL_VFS_POIN
a9b0: 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 TER] opcode find
a9c0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
a9d0: 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 he top-level.**
a9e0: 5b 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c [VFSes] currentl
a9f0: 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 y in use. ^(The
aa00: 20 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a argument X in.*
aa10: 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 * sqlite3_file_c
aa20: 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 ontrol(db,SQLITE
aa30: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 _FCNTL_VFS_POINT
aa40: 45 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a ER,X) must be.**
aa50: 20 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 of type "[sqlit
aa60: 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 e3_vfs] **". Th
aa70: 69 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 is opcodes will
aa80: 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 set *X.** to a p
aa90: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f ointer to the to
aaa0: 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a p-level VFS.)^.*
aab0: 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 * ^When there ar
aac0: 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 e multiple VFS s
aad0: 68 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 hims in the stac
aae0: 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 k, this opcode f
aaf0: 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 inds the.** uppe
ab00: 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 r-most shim only
ab10: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
ab20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
ab30: 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 A]].** ^Whenever
ab40: 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 a [PRAGMA] stat
ab50: 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c ement is parsed,
ab60: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 an [SQLITE_FCNT
ab70: 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 L_PRAGMA] .** fi
ab80: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 le control is se
ab90: 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b nt to the open [
aba0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
abb0: 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 ject correspondi
abc0: 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 ng.** to the dat
abd0: 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 abase file to wh
abe0: 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 ich the pragma s
abf0: 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e tatement refers.
ac00: 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a ^The argument.*
ac10: 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 * to the [SQLITE
ac20: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 _FCNTL_PRAGMA] f
ac30: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 ile control is a
ac40: 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f n array of.** po
ac50: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 inters to string
ac60: 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 s (char**) in wh
ac70: 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 ich the second e
ac80: 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 lement of the ar
ac90: 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 ray.** is the na
aca0: 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 me of the pragma
acb0: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 and the third e
acc0: 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 lement is the ar
acd0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a gument to the.**
ace0: 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 pragma or NULL
acf0: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 if the pragma ha
ad00: 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 s no argument.
ad10: 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 ^The handler for
ad20: 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 an.** [SQLITE_F
ad30: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c CNTL_PRAGMA] fil
ad40: 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 e control can op
ad50: 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 tionally make th
ad60: 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a e first element.
ad70: 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a ** of the char**
ad80: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 argument point
ad90: 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 to a string obta
ada0: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 ined from [sqlit
adb0: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a e3_mprintf()].**
adc0: 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 or the equivale
add0: 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 nt and that stri
ade0: 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 ng will become t
adf0: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 he result of the
ae00: 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 pragma or.** th
ae10: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
ae20: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 if the pragma fa
ae30: 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 ils. ^If the.**
ae40: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
ae50: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 AGMA] file contr
ae60: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ol returns [SQLI
ae70: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 TE_NOTFOUND], th
ae80: 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 en normal .** [P
ae90: 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e RAGMA] processin
aea0: 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 g continues. ^I
aeb0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 f the [SQLITE_FC
aec0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 NTL_PRAGMA].** f
aed0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 ile control retu
aee0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c rns [SQLITE_OK],
aef0: 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 then the parser
af00: 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 assumes that th
af10: 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e e.** VFS has han
af20: 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 dled the PRAGMA
af30: 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 itself and the p
af40: 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 arser generates
af50: 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 a no-op.** prepa
af60: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 red statement if
af70: 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 result string i
af80: 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 s NULL, or that
af90: 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a returns a copy.*
afa0: 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 * of the result
afb0: 73 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 string if the st
afc0: 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c ring is non-NULL
afd0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 ..** ^If the [SQ
afe0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
aff0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 A] file control
b000: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 returns.** any r
b010: 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 esult code other
b020: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b than [SQLITE_OK
b030: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 ] or [SQLITE_NOT
b040: 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 FOUND], that mea
b050: 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 ns.** that the V
b060: 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 FS encountered a
b070: 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 n error while ha
b080: 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 ndling the [PRAG
b090: 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 MA] and the.** c
b0a0: 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 ompilation of th
b0b0: 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 e PRAGMA fails w
b0c0: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e ith an error. ^
b0d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
b0e0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c L_PRAGMA].** fil
b0f0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 e control occurs
b100: 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e at the beginnin
b110: 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 g of pragma stat
b120: 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 ement analysis a
b130: 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 nd so.** it is a
b140: 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 ble to override
b150: 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 built-in [PRAGMA
b160: 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a ] statements..**
b170: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
b180: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c _FCNTL_BUSYHANDL
b190: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ER]].** ^The [SQ
b1a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 LITE_FCNTL_BUSYH
b1b0: 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d ANDLER].** file-
b1c0: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 control may be i
b1d0: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 nvoked by SQLite
b1e0: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 on the database
b1f0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 file handle.**
b200: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 shortly after it
b210: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 is opened in or
b220: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 der to provide a
b230: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 custom VFS with
b240: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 access.** to th
b250: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 e connections bu
b260: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 sy-handler callb
b270: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e ack. The argumen
b280: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f t is of type (vo
b290: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 id **).** - an a
b2a0: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 rray of two (voi
b2b0: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 d *) values. The
b2c0: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 first (void *)
b2d0: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a actually points.
b2e0: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e ** to a function
b2f0: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a of type (int (*
b300: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f )(void *)). In o
b310: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 rder to invoke t
b320: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a he connections.*
b330: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 * busy-handler,
b340: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 this function sh
b350: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 ould be invoked
b360: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 with the second
b370: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 (void *) in.** t
b380: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 he array as the
b390: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 only argument. I
b3a0: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e f it returns non
b3b0: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 -zero, then the
b3c0: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f operation.** sho
b3d0: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 uld be retried.
b3e0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 If it returns ze
b3f0: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 ro, the custom V
b400: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f FS should abando
b410: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 n the.** current
b420: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a operation..**.*
b430: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
b440: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d CNTL_TEMPFILENAM
b450: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 E]].** ^Applicat
b460: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 ion can invoke t
b470: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
b480: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 _TEMPFILENAME] f
b490: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 ile-control.** t
b4a0: 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 o have SQLite ge
b4b0: 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 nerate a.** temp
b4c0: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 orary filename u
b4d0: 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c sing the same al
b4e0: 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 gorithm that is
b4f0: 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 followed to gene
b500: 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 rate.** temporar
b510: 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 y filenames for
b520: 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 TEMP tables and
b530: 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 other internal u
b540: 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 ses. The.** arg
b550: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 ument should be
b560: 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 a char** which w
b570: 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 ill be filled wi
b580: 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a th the filename.
b590: 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 ** written into
b5a0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
b5b0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
b5c0: 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 lloc()]. The ca
b5d0: 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 ller should.** i
b5e0: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 nvoke [sqlite3_f
b5f0: 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 ree()] on the re
b600: 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 sult to avoid a
b610: 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a memory leak..**.
b620: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
b630: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d FCNTL_MMAP_SIZE]
b640: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
b650: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 _FCNTL_MMAP_SIZE
b660: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 ] file control i
b670: 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 s used to query
b680: 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 or set the.** ma
b690: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
b6a0: 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 bytes that will
b6b0: 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f be used for memo
b6c0: 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a ry-mapped I/O..*
b6d0: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 * The argument i
b6e0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
b6f0: 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 value of type s
b700: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 qlite3_int64 tha
b710: 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 t.** is an advis
b720: 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 ory maximum numb
b730: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
b740: 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 he file to memor
b750: 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 y map. The.** p
b760: 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 ointer is overwr
b770: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f itten with the o
b780: 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c ld value. The l
b790: 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e imit is not chan
b7a0: 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 ged if.** the va
b7b0: 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 lue originally p
b7c0: 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 ointed to is neg
b7d0: 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 ative, and so th
b7e0: 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 e current limit
b7f0: 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 .** can be queri
b800: 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e ed by passing in
b810: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
b820: 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e negative number.
b830: 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 This.** file-c
b840: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 ontrol is used i
b850: 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 nternally to imp
b860: 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d lement [PRAGMA m
b870: 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a map_size]..**.**
b880: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
b890: 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 NTL_TRACE]].** T
b8a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
b8b0: 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e _TRACE] file con
b8c0: 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 trol provides ad
b8d0: 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 visory informati
b8e0: 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 on.** to the VFS
b8f0: 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 about what the
b900: 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 higher layers of
b910: 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 the SQLite stac
b920: 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 k are doing..**
b930: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f This file contro
b940: 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d l is used by som
b950: 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 e VFS activity t
b960: 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a racing [shims]..
b970: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 ** The argument
b980: 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e is a zero-termin
b990: 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 ated string. Hi
b9a0: 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 gher layers in t
b9b0: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 he.** SQLite sta
b9c0: 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 ck may generate
b9d0: 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 instances of thi
b9e0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 s file control i
b9f0: 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 f.** the [SQLITE
ba00: 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 _USE_FCNTL_TRACE
ba10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
ba20: 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 ption is enabled
ba30: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
ba40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d LITE_FCNTL_HAS_M
ba50: 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 OVED]].** The [S
ba60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f QLITE_FCNTL_HAS_
ba70: 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 MOVED] file cont
ba80: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 rol interprets i
ba90: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 ts argument as a
baa0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 .** pointer to a
bab0: 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 n integer and it
bac0: 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 writes a boolea
bad0: 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 n into that inte
bae0: 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a ger depending.**
baf0: 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e on whether or n
bb00: 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 ot the file has
bb10: 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f been renamed, mo
bb20: 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 ved, or deleted
bb30: 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 since it.** was
bb40: 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a first opened..**
bb50: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
bb60: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 _FCNTL_WIN32_GET
bb70: 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 _HANDLE]].** The
bb80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 [SQLITE_FCNTL_W
bb90: 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d IN32_GET_HANDLE]
bba0: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 opcode can be u
bbb0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 sed to obtain th
bbc0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 e.** underlying
bbd0: 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 native file hand
bbe0: 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 le associated wi
bbf0: 74 68 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 th a file handle
bc00: 2e 20 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 . This file.**
bc10: 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 control interpre
bc20: 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 ts its argument
bc30: 61 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 as a pointer to
bc40: 61 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 a native file ha
bc50: 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 ndle and.** writ
bc60: 65 73 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 es the resulting
bc70: 20 76 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a value there..**
bc80: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
bc90: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 _FCNTL_WIN32_SET
bca0: 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 _HANDLE]].** The
bcb0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 [SQLITE_FCNTL_W
bcc0: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d IN32_SET_HANDLE]
bcd0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
bce0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 for debugging.
bcf0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 This.** opcode c
bd00: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 auses the xFileC
bd10: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f ontrol method to
bd20: 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 swap the file h
bd30: 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f andle with the o
bd40: 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f ne.** pointed to
bd50: 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67 by the pArg arg
bd60: 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 ument. This cap
bd70: 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 ability is used
bd80: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a during testing.*
bd90: 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 * and only needs
bda0: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
bdb0: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 when SQLITE_TES
bdc0: 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a T is defined..**
bdd0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
bde0: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b _FCNTL_WAL_BLOCK
bdf0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
be00: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 E_FCNTL_WAL_BLOC
be10: 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 K] is a signal t
be20: 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 o the VFS layer
be30: 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a that it might.**
be40: 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 be advantageous
be50: 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 to block on the
be60: 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 next WAL lock i
be70: 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f f the lock is no
be80: 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a t immediately.**
be90: 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 available. The
bea0: 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 WAL subsystem i
beb0: 73 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 ssues this signa
bec0: 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a l during rare.**
bed0: 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 circumstances i
bee0: 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 n order to fix a
bef0: 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 problem with pr
bf00: 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e iority inversion
bf10: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e ..** Application
bf20: 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 s should <em>not
bf30: 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 </em> use this f
bf40: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a ile-control..**.
bf50: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
bf60: 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a FCNTL_ZIPVFS]].*
bf70: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
bf80: 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f NTL_ZIPVFS] opco
bf90: 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 de is implemente
bfa0: 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 d by zipvfs only
bfb0: 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 . All other.** V
bfc0: 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e FS should return
bfd0: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 SQLITE_NOTFOUND
bfe0: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 for this opcode
bff0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
c000: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d LITE_FCNTL_RBU]]
c010: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
c020: 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 FCNTL_RBU] opcod
c030: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 e is implemented
c040: 20 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 by the special
c050: 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 VFS used by.** t
c060: 68 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e he RBU extension
c070: 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 only. All othe
c080: 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 r VFS should ret
c090: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f urn SQLITE_NOTFO
c0a0: 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 UND for.** this
c0b0: 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 opcode. .** </u
c0c0: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
c0d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
c0e0: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 TATE
c0f0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
c100: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f ITE_FCNTL_GET_LO
c110: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 CKPROXYFILE
c120: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
c130: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 TE_FCNTL_SET_LOC
c140: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 KPROXYFILE
c150: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 3.#define SQLIT
c160: 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 E_FCNTL_LAST_ERR
c170: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 NO
c180: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
c190: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 _FCNTL_SIZE_HINT
c1a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 5
c1b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c1c0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 FCNTL_CHUNK_SIZE
c1d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 6.
c1e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
c1f0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 CNTL_FILE_POINTE
c200: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 R 7.#
c210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
c220: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 NTL_SYNC_OMITTED
c230: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 8.#d
c240: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
c250: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 TL_WIN32_AV_RETR
c260: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 Y 9.#de
c270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
c280: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 L_PERSIST_WAL
c290: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 10.#def
c2a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
c2b0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 _OVERWRITE
c2c0: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 11.#defi
c2d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
c2e0: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 VFSNAME
c2f0: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 12.#defin
c300: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 e SQLITE_FCNTL_P
c310: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
c320: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 TE 13.#define
c330: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 SQLITE_FCNTL_PR
c340: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 AGMA
c350: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 14.#define
c360: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 SQLITE_FCNTL_BUS
c370: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 YHANDLER
c380: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 15.#define S
c390: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 QLITE_FCNTL_TEMP
c3a0: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 FILENAME
c3b0: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 16.#define SQ
c3c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f LITE_FCNTL_MMAP_
c3d0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 SIZE
c3e0: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 18.#define SQL
c3f0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 ITE_FCNTL_TRACE
c400: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
c410: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 19.#define SQLI
c420: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 TE_FCNTL_HAS_MOV
c430: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ED
c440: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 20.#define SQLIT
c450: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 E_FCNTL_SYNC
c460: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
c470: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
c480: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 _FCNTL_COMMIT_PH
c490: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 ASETWO 22
c4a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c4b0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f FCNTL_WIN32_SET_
c4c0: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a HANDLE 23.
c4d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
c4e0: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 CNTL_WAL_BLOCK
c4f0: 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 23 24.#
c500: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
c510: 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20 NTL_ZIPVFS
c520: 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 64 25.#d
c530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
c540: 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20 20 TL_RBU
c550: 20 20 20 20 20 20 20 20 20 20 32 36 0a 23 64 65 26.#de
c560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
c570: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 L_VFS_POINTER
c580: 20 20 20 20 20 20 20 20 20 32 37 0a 23 64 65 66 27.#def
c590: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
c5a0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 _JOURNAL_POINTER
c5b0: 20 20 20 20 20 20 20 20 32 38 0a 23 64 65 66 69 28.#defi
c5c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
c5d0: 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 WIN32_GET_HANDLE
c5e0: 20 20 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e 29.#defin
c5f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 e SQLITE_FCNTL_P
c600: 44 42 20 20 20 20 20 20 20 20 20 20 20 20 20 20 DB
c610: 20 20 20 20 20 20 33 30 0a 0a 2f 2a 20 64 65 70 30../* dep
c620: 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f recated names */
c630: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c640: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c GET_LOCKPROXYFIL
c650: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 E SQLITE_FC
c660: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 NTL_GET_LOCKPROX
c670: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 YFILE.#define SQ
c680: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f LITE_SET_LOCKPRO
c690: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 XYFILE SQLI
c6a0: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 TE_FCNTL_SET_LOC
c6b0: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 KPROXYFILE.#defi
c6c0: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 ne SQLITE_LAST_E
c6d0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 RRNO
c6e0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 SQLITE_FCNTL_LA
c6f0: 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a ST_ERRNO.../*.**
c700: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 CAPI3REF: Mutex
c710: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 Handle.**.** Th
c720: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 e mutex module w
c730: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 ithin SQLite def
c740: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 ines [sqlite3_mu
c750: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a tex] to be an.**
c760: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 abstract type f
c770: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 or a mutex objec
c780: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 t. The SQLite c
c790: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a ore never looks.
c7a0: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e ** at the intern
c7b0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f al representatio
c7c0: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 n of an [sqlite3
c7d0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c _mutex]. It onl
c7e0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 y.** deals with
c7f0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 pointers to the
c800: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 [sqlite3_mutex]
c810: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 object..**.** Mu
c820: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 texes are create
c830: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
c840: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e _mutex_alloc()].
c850: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
c860: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ct sqlite3_mutex
c870: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a sqlite3_mutex;.
c880: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
c890: 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 Loadable Extens
c8a0: 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 ion Thunk.**.**
c8b0: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 A pointer to the
c8c0: 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f opaque sqlite3_
c8d0: 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 api_routines str
c8e0: 75 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64 ucture is passed
c8f0: 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 as.** the third
c900: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e parameter to en
c910: 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c try points of [l
c920: 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f oadable extensio
c930: 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 ns]. This.** st
c940: 72 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 ructure must be
c950: 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 typedefed in ord
c960: 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e er to work aroun
c970: 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 d compiler warni
c980: 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 ngs.** on some p
c990: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 latforms..*/.typ
c9a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
c9b0: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 te3_api_routines
c9c0: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 sqlite3_api_rou
c9d0: 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tines;../*.** CA
c9e0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
c9f0: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a face Object.**.*
ca00: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
ca10: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
ca20: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 object defines
ca30: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 the interface be
ca40: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c tween.** the SQL
ca50: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 ite core and the
ca60: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 underlying oper
ca70: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 ating system. T
ca80: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 he "vfs".** in t
ca90: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f he name of the o
caa0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 bject stands for
cab0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 "virtual file s
cac0: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 ystem". See.**
cad0: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 the [VFS | VFS d
cae0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f ocumentation] fo
caf0: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d r further inform
cb00: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ation..**.** The
cb10: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 value of the iV
cb20: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 ersion field is
cb30: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 initially 1 but
cb40: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e may be larger in
cb50: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 .** future versi
cb60: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 ons of SQLite.
cb70: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 Additional field
cb80: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 s may be appende
cb90: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a d to this.** obj
cba0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 ect when the iVe
cbb0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 rsion value is i
cbc0: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 ncreased. Note
cbd0: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 that the structu
cbe0: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c re.** of the sql
cbf0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 ite3_vfs object
cc00: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 changes in the t
cc10: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 ransaction betwe
cc20: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 en.** SQLite ver
cc30: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 sion 3.5.9 and 3
cc40: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 .6.0 and yet the
cc50: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 iVersion field
cc60: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 was not.** modif
cc70: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ied..**.** The s
cc80: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 zOsFile field is
cc90: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
cca0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c subclassed [sql
ccb0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 ite3_file].** st
ccc0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 ructure used by
ccd0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 this VFS. mxPat
cce0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 hname is the max
ccf0: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a imum length of.*
cd00: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 * a pathname in
cd10: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 this VFS..**.**
cd20: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 Registered sqlit
cd30: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 e3_vfs objects a
cd40: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e re kept on a lin
cd50: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 ked list formed
cd60: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 by.** the pNext
cd70: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 pointer. The [s
cd80: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 qlite3_vfs_regis
cd90: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ter()].** and [s
cda0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 qlite3_vfs_unreg
cdb0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 ister()] interfa
cdc0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 ces manage this
cdd0: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 list.** in a thr
cde0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 ead-safe way. T
cdf0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f he [sqlite3_vfs_
ce00: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 find()] interfac
ce10: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 e.** searches th
ce20: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 e list. Neither
ce30: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
ce40: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 code nor the VF
ce50: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 S.** implementat
ce60: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 ion should use t
ce70: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 he pNext pointer
ce80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 ..**.** The pNex
ce90: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f t field is the o
cea0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 nly field in the
ceb0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 sqlite3_vfs.**
cec0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 structure that S
ced0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 QLite will ever
cee0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 modify. SQLite
cef0: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 will only access
cf00: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 .** or modify th
cf10: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 is field while h
cf20: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 olding a particu
cf30: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 lar static mutex
cf40: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
cf50: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 tion should neve
cf60: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e r modify anythin
cf70: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c g within the sql
cf80: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 ite3_vfs.** obje
cf90: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 ct once the obje
cfa0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 ct has been regi
cfb0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 stered..**.** Th
cfc0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f e zName field ho
cfd0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 lds the name of
cfe0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 the VFS module.
cff0: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a The name must.*
d000: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f * be unique acro
d010: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c ss all VFS modul
d020: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 es..**.** [[sqli
d030: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a te3_vfs.xOpen]].
d040: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 ** ^SQLite guara
d050: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a ntees that the z
d060: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
d070: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 er to xOpen.** i
d080: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 s either a NULL
d090: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e pointer or strin
d0a0: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 g obtained.** fr
d0b0: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 om xFullPathname
d0c0: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f () with an optio
d0d0: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 nal suffix added
d0e0: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 ..** ^If a suffi
d0f0: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 x is added to th
d100: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 e zFilename para
d110: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a meter, it will.*
d120: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 * consist of a s
d130: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 ingle "-" charac
d140: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 ter followed by
d150: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 no more than.**
d160: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 11 alphanumeric
d170: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 and/or "-" chara
d180: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 cters..** ^SQLit
d190: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e e further guaran
d1a0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 tees that.** the
d1b0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 string will be
d1c0: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e valid and unchan
d1d0: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 ged until xClose
d1e0: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e () is.** called.
d1f0: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 Because of the
d200: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 previous sentenc
d210: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 e,.** the [sqlit
d220: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 e3_file] can saf
d230: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e ely store a poin
d240: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 ter to the.** fi
d250: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 lename if it nee
d260: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 ds to remember t
d270: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 he filename for
d280: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 some reason..**
d290: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 If the zFilename
d2a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f parameter to xO
d2b0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f pen is a NULL po
d2c0: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e inter then xOpen
d2d0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 .** must invent
d2e0: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 its own temporar
d2f0: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 y name for the f
d300: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 ile. ^Whenever
d310: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d the .** xFilenam
d320: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e e parameter is N
d330: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f ULL it will also
d340: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 be the case tha
d350: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 t the.** flags p
d360: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e arameter will in
d370: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 clude [SQLITE_OP
d380: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
d390: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 ]..**.** The fla
d3a0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
d3b0: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 Open() includes
d3c0: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a all bits set in.
d3d0: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 ** the flags arg
d3e0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 ument to [sqlite
d3f0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 3_open_v2()]. O
d400: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 r if [sqlite3_op
d410: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c en()].** or [sql
d420: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 ite3_open16()] i
d430: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 s used, then fla
d440: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c gs includes at l
d450: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f east.** [SQLITE_
d460: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 OPEN_READWRITE]
d470: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 | [SQLITE_OPEN_C
d480: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 REATE]. .** If x
d490: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 Open() opens a f
d4a0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 ile read-only th
d4b0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 en it sets *pOut
d4c0: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c Flags to.** incl
d4d0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ude [SQLITE_OPEN
d4e0: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 _READONLY]. Oth
d4f0: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 er bits in *pOut
d500: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 Flags may be set
d510: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 ..**.** ^(SQLite
d520: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f will also add o
d530: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
d540: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 ing flags to the
d550: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c xOpen().** call
d560: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 , depending on t
d570: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 he object being
d580: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 opened:.**.** <u
d590: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c l>.** <li> [SQL
d5a0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
d5b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
d5c0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 TE_OPEN_MAIN_JOU
d5d0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
d5e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
d5f0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
d600: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
d610: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
d620: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 [SQLITE_OPEN_T
d630: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 RANSIENT_DB].**
d640: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
d650: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a EN_SUBJOURNAL].*
d660: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
d670: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
d680: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
d690: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a QLITE_OPEN_WAL].
d6a0: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a ** </ul>)^.**.**
d6b0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d The file I/O im
d6c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e plementation can
d6d0: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 use the object
d6e0: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a type flags to.**
d6f0: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 change the way
d700: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 it deals with fi
d710: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c les. For exampl
d720: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f e, an applicatio
d730: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e n.** that does n
d740: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 ot care about cr
d750: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 ash recovery or
d760: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d rollback might m
d770: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 ake.** the open
d780: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c of a journal fil
d790: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 e a no-op. Writ
d7a0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e es to this journ
d7b0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f al would.** also
d7c0: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 be no-ops, and
d7d0: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 any attempt to r
d7e0: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 ead the journal
d7f0: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 would return.**
d800: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f SQLITE_IOERR. O
d810: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 r the implementa
d820: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 tion might recog
d830: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 nize that a data
d840: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c base.** file wil
d850: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d l be doing page-
d860: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 aligned sector r
d870: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 eads and writes
d880: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f in a random.** o
d890: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 rder and set up
d8a0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 its I/O subsyste
d8b0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a m accordingly..*
d8c0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 *.** SQLite migh
d8d0: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f t also add one o
d8e0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
d8f0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 flags to the xOp
d900: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a en method:.**.**
d910: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
d920: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
d930: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 EONCLOSE].** <li
d940: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 > [SQLITE_OPEN_E
d950: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 XCLUSIVE].** </u
d960: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 l>.**.** The [SQ
d970: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
d980: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 ONCLOSE] flag me
d990: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f ans the file sho
d9a0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 uld be.** delete
d9b0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f d when it is clo
d9c0: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 sed. ^The [SQLI
d9d0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
d9e0: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 CLOSE].** will b
d9f0: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 e set for TEMP d
da00: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 atabases and the
da10: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 ir journals, tra
da20: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 nsient.** databa
da30: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 ses, and subjour
da40: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 nals..**.** ^The
da50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
da60: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 CLUSIVE] flag is
da70: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 always used in
da80: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 conjunction.** w
da90: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
daa0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 OPEN_CREATE] fla
dab0: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 g, which are bot
dac0: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e h directly.** an
dad0: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f alogous to the O
dae0: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 _EXCL and O_CREA
daf0: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 T flags of the P
db00: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 OSIX open().** A
db10: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f PI. The SQLITE_
db20: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 OPEN_EXCLUSIVE f
db30: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 lag, when paired
db40: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 with the .** SQ
db50: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
db60: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 , is used to ind
db70: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 icate that file
db80: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a should always.**
db90: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 be created, and
dba0: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 that it is an e
dbb0: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 rror if it alrea
dbc0: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 dy exists..** It
dbd0: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 is <i>not</i> u
dbe0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 sed to indicate
dbf0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 the file should
dc00: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f be opened .** fo
dc10: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 r exclusive acce
dc20: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 ss..**.** ^At le
dc30: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 ast szOsFile byt
dc40: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 es of memory are
dc50: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 allocated by SQ
dc60: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 Lite.** to hold
dc70: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
dc80: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 le] structure pa
dc90: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 ssed as the thir
dca0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f d.** argument to
dcb0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 xOpen. The xOp
dcc0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e en method does n
dcd0: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c ot have to.** al
dce0: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 locate the struc
dcf0: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 ture; it should
dd00: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e just fill it in.
dd10: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 Note that.** t
dd20: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 he xOpen method
dd30: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c must set the sql
dd40: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
dd50: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 ds to either.**
dd60: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 a valid [sqlite3
dd70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
dd80: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 ect or to NULL.
dd90: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a xOpen must do.*
dda0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 * this even if t
ddb0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 he open fails.
ddc0: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 SQLite expects t
ddd0: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f hat the sqlite3_
dde0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a file.pMethods.**
ddf0: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 element will be
de00: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 valid after xOp
de10: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 en returns regar
de20: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 dless of the suc
de30: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 cess.** or failu
de40: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 re of the xOpen
de50: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 call..**.** [[sq
de60: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 lite3_vfs.xAcces
de70: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 s]].** ^The flag
de80: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 s argument to xA
de90: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b ccess() may be [
dea0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
deb0: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 ISTS].** to test
dec0: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e for the existen
ded0: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 ce of a file, or
dee0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
def0: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a READWRITE] to.**
df00: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 test whether a
df10: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 file is readable
df20: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f and writable, o
df30: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 r [SQLITE_ACCESS
df40: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 _READ].** to tes
df50: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 t whether a file
df60: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 is at least rea
df70: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c dable. The fil
df80: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 e can be a.** di
df90: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e rectory..**.** ^
dfa0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 SQLite will alwa
dfb0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c ys allocate at l
dfc0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b east mxPathname+
dfd0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 1 bytes for the.
dfe0: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 ** output buffer
dff0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 xFullPathname.
e000: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 The exact size
e010: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 of the output bu
e020: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 ffer.** is also
e030: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 passed as a para
e040: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d meter to both m
e050: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f ethods. If the o
e060: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 utput buffer.**
e070: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f is not large eno
e080: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e ugh, [SQLITE_CAN
e090: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 TOPEN] should be
e0a0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 returned. Since
e0b0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 this is.** hand
e0c0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 led as a fatal e
e0d0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 rror by SQLite,
e0e0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 vfs implementati
e0f0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 ons should endea
e100: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e vor.** to preven
e110: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e t this by settin
e120: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 g mxPathname to
e130: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c a sufficiently l
e140: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a arge value..**.*
e150: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 * The xRandomnes
e160: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 s(), xSleep(), x
e170: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 CurrentTime(), a
e180: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 nd xCurrentTimeI
e190: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 nt64().** interf
e1a0: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 aces are not str
e1b0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 ictly a part of
e1c0: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 the filesystem,
e1d0: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 but they are.**
e1e0: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 included in the
e1f0: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f VFS structure fo
e200: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a r completeness..
e210: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 ** The xRandomne
e220: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 ss() function at
e230: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e tempts to return
e240: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a nBytes bytes.**
e250: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 of good-quality
e260: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f randomness into
e270: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 zOut. The retu
e280: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 rn value is.** t
e290: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 he actual number
e2a0: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e of bytes of ran
e2b0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 domness obtained
e2c0: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 ..** The xSleep(
e2d0: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 ) method causes
e2e0: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 the calling thre
e2f0: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 ad to sleep for
e300: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 at.** least the
e310: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 number of micros
e320: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e econds given. ^
e330: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 The xCurrentTime
e340: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 ().** method ret
e350: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 urns a Julian Da
e360: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 y Number for the
e370: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e current date an
e380: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 d time as.** a f
e390: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 loating point va
e3a0: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 lue..** ^The xCu
e3b0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 rrentTimeInt64()
e3c0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c method returns,
e3d0: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 as an integer,
e3e0: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 the Julian.** Da
e3f0: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c y Number multipl
e400: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 ied by 86400000
e410: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d (the number of m
e420: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a illiseconds in .
e430: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 ** a 24-hour day
e440: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ). .** ^SQLite
e450: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 will use the xCu
e460: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 rrentTimeInt64()
e470: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 method to get t
e480: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 he current.** da
e490: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 te and time if t
e4a0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 hat method is av
e4b0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 ailable (if iVer
e4c0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a sion is 2 or .**
e4d0: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 greater and the
e4e0: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 function pointe
e4f0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 r is not NULL) a
e500: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 nd will fall bac
e510: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 k.** to xCurrent
e520: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 Time() if xCurre
e530: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 ntTimeInt64() is
e540: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a unavailable..**
e550: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 .** ^The xSetSys
e560: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 temCall(), xGetS
e570: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 ystemCall(), and
e580: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c xNestSystemCall
e590: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a () interfaces.**
e5a0: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 are not used by
e5b0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 the SQLite core
e5c0: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 . These optiona
e5d0: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 l interfaces are
e5e0: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 provided.** by
e5f0: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 some VFSes to fa
e600: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 cilitate testing
e610: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 of the VFS code
e620: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 . By overriding
e630: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 .** system calls
e640: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 with functions
e650: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f under its contro
e660: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 l, a test progra
e670: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 m can.** simulat
e680: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 e faults and err
e690: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 or conditions th
e6a0: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 at would otherwi
e6b0: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a se be difficult.
e6c0: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 ** or impossible
e6d0: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 to induce. The
e6e0: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 set of system c
e6f0: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 alls that can be
e700: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 overridden.** v
e710: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 aries from one V
e720: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 FS to another, a
e730: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 nd from one vers
e740: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ion of the same
e750: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 VFS to the.** ne
e760: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e xt. Application
e770: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 s that use these
e780: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 interfaces must
e790: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 be prepared for
e7a0: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f any.** or all o
e7b0: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 f these interfac
e7c0: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 es to be NULL or
e7d0: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 for their behav
e7e0: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a ior to change.**
e7f0: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 from one releas
e800: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 e to the next.
e810: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 Applications mus
e820: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f t not attempt to
e830: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f access.** any o
e840: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 f these methods
e850: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 if the iVersion
e860: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 of the VFS is le
e870: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 ss than 3..*/.ty
e880: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
e890: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 ite3_vfs sqlite3
e8a0: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f _vfs;.typedef vo
e8b0: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 id (*sqlite3_sys
e8c0: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b call_ptr)(void);
e8d0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
e8e0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 vfs {. int iVer
e8f0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 sion;
e900: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 /* Structure ve
e910: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 rsion number (cu
e920: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 rrently 3) */.
e930: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 int szOsFile;
e940: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 /* Size
e950: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 of subclassed s
e960: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 qlite3_file */.
e970: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b int mxPathname;
e980: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
e990: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 imum file pathna
e9a0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 me length */. s
e9b0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 qlite3_vfs *pNex
e9c0: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 t; /* Next
e9d0: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a registered VFS *
e9e0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
e9f0: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 zName; /*
ea00: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 Name of this vir
ea10: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d tual file system
ea20: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 */. void *pApp
ea30: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f Data; /
ea40: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 * Pointer to app
ea50: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 lication-specifi
ea60: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 c data */. int
ea70: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 (*xOpen)(sqlite3
ea80: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
ea90: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 r *zName, sqlite
eaa0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 3_file*,.
eab0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 int flag
eac0: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 s, int *pOutFlag
ead0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c s);. int (*xDel
eae0: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ete)(sqlite3_vfs
eaf0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
eb00: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 Name, int syncDi
eb10: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 r);. int (*xAcc
eb20: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ess)(sqlite3_vfs
eb30: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
eb40: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c Name, int flags,
eb50: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a int *pResOut);.
eb60: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 int (*xFullPat
eb70: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 hname)(sqlite3_v
eb80: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
eb90: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 *zName, int nOut
eba0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 , char *zOut);.
ebb0: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e void *(*xDlOpen
ebc0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
ebd0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c const char *zFil
ebe0: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 ename);. void (
ebf0: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 *xDlError)(sqlit
ec00: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 e3_vfs*, int nBy
ec10: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 te, char *zErrMs
ec20: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 g);. void (*(*x
ec30: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 DlSym)(sqlite3_v
ec40: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 fs*,void*, const
ec50: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 char *zSymbol))
ec60: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 (void);. void (
ec70: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 *xDlClose)(sqlit
ec80: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b e3_vfs*, void*);
ec90: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d . int (*xRandom
eca0: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 ness)(sqlite3_vf
ecb0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 s*, int nByte, c
ecc0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e har *zOut);. in
ecd0: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 t (*xSleep)(sqli
ece0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 te3_vfs*, int mi
ecf0: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 croseconds);. i
ed00: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d nt (*xCurrentTim
ed10: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
ed20: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 double*);. int
ed30: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 (*xGetLastError
ed40: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
ed50: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 int, char *);.
ed60: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 /*. ** The meth
ed70: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e ods above are in
ed80: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 version 1 of th
ed90: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a e sqlite_vfs obj
eda0: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 ect. ** definit
edb0: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 ion. Those that
edc0: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 follow are adde
edd0: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f d in version 2 o
ede0: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 r later. */. i
edf0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d nt (*xCurrentTim
ee00: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f eInt64)(sqlite3_
ee10: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e vfs*, sqlite3_in
ee20: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a t64*);. /*. **
ee30: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f The methods abo
ee40: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f ve are in versio
ee50: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 ns 1 and 2 of th
ee60: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a e sqlite_vfs obj
ee70: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 ect.. ** Those
ee80: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 below are for ve
ee90: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 rsion 3 and grea
eea0: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 ter.. */. int
eeb0: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c (*xSetSystemCall
eec0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
eed0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
eee0: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 e, sqlite3_sysca
eef0: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 ll_ptr);. sqlit
ef00: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 e3_syscall_ptr (
ef10: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 *xGetSystemCall)
ef20: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
ef30: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
ef40: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 );. const char
ef50: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 *(*xNextSystemCa
ef60: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ll)(sqlite3_vfs*
ef70: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
ef80: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 ame);. /*. **
ef90: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
efa0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
efb0: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 s 1 through 3 of
efc0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 the sqlite_vfs
efd0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 object.. ** New
efe0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 fields may be a
eff0: 70 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 ppended in futur
f000: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 e versions. The
f010: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 iVersion. ** v
f020: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d alue will increm
f030: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 ent whenever thi
f040: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f s happens. . */
f050: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
f060: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 REF: Flags for t
f070: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d he xAccess VFS m
f080: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ethod.**.** Thes
f090: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
f0a0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 nts can be used
f0b0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 as the third par
f0c0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 ameter to.** the
f0d0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 xAccess method
f0e0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 of an [sqlite3_v
f0f0: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 fs] object. The
f100: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 y determine.** w
f110: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d hat kind of perm
f120: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 issions the xAcc
f130: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f ess method is lo
f140: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 oking for..** Wi
f150: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
f160: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 _EXISTS, the xAc
f170: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 cess method.** s
f180: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 imply checks whe
f190: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 ther the file ex
f1a0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 ists..** With SQ
f1b0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
f1c0: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 WRITE, the xAcce
f1d0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 ss method.** che
f1e0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
f1f0: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 named directory
f200: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 is both readable
f210: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a and writable.**
f220: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 (in other words
f230: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 , if files can b
f240: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 e added, removed
f250: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 , and renamed wi
f260: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 thin.** the dire
f270: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 ctory)..** The S
f280: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
f290: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 DWRITE constant
f2a0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 is currently use
f2b0: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a d only by the.**
f2c0: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 [temp_store_dir
f2d0: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 ectory pragma],
f2e0: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c though this coul
f2f0: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 d change in a fu
f300: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 ture.** release
f310: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 of SQLite..** Wi
f320: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
f330: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 _READ, the xAcce
f340: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 ss method.** che
f350: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
f360: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 file is readable
f370: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 . The SQLITE_AC
f380: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 CESS_READ consta
f390: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 nt is.** current
f3a0: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 ly unused, thoug
f3b0: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 h it might be us
f3c0: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 ed in a future r
f3d0: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c elease of.** SQL
f3e0: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ite..*/.#define
f3f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
f400: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e ISTS 0.#defin
f410: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f e SQLITE_ACCESS_
f420: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a READWRITE 1 /*
f430: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 Used by PRAGMA
f440: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 temp_store_direc
f450: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 tory */.#define
f460: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
f470: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 AD 2 /* U
f480: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 nused */../*.**
f490: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 CAPI3REF: Flags
f4a0: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b for the xShmLock
f4b0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a VFS method.**.*
f4c0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
f4d0: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 constants define
f4e0: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 the various loc
f4f0: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a king operations.
f500: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 ** allowed by th
f510: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f e xShmLock metho
f520: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f d of [sqlite3_io
f530: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a _methods]. The.
f540: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 ** following are
f550: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 the only legal
f560: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 combinations of
f570: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 flags to the.**
f580: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a xShmLock method:
f590: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
f5a0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f li> SQLITE_SHM_
f5b0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 LOCK | SQLITE_SH
f5c0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e M_SHARED.** <li>
f5d0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 SQLITE_SHM_LOC
f5e0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 K | SQLITE_SHM_E
f5f0: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e XCLUSIVE.** <li>
f600: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c SQLITE_SHM_UNL
f610: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
f620: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 _SHARED.** <li>
f630: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f SQLITE_SHM_UNLO
f640: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
f650: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 EXCLUSIVE.** </u
f660: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e l>.**.** When un
f670: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d locking, the sam
f680: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c e SHARED or EXCL
f690: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 USIVE flag must
f6a0: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a be supplied as.*
f6b0: 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 * was given on t
f6c0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
f6d0: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 lock. .**.** T
f6e0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 he xShmLock meth
f6f0: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f od can transitio
f700: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b n between unlock
f710: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 ed and SHARED or
f720: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f .** between unlo
f730: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 cked and EXCLUSI
f740: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 VE. It cannot t
f750: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 ransition betwee
f760: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 n SHARED.** and
f770: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 EXCLUSIVE..*/.#d
f780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d efine SQLITE_SHM
f790: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a _UNLOCK 1.
f7a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
f7b0: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 HM_LOCK
f7c0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
f7d0: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 _SHM_SHARED
f7e0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
f7f0: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
f800: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 8../*.** CAP
f810: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 I3REF: Maximum x
f820: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a ShmLock index.**
f830: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b .** The xShmLock
f840: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 method on [sqli
f850: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
f860: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a may use values.*
f870: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 * between 0 and
f880: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 this upper bound
f890: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 as its "offset"
f8a0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 argument..** Th
f8b0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 e SQLite core wi
f8c0: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 ll never attempt
f8d0: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 to acquire or r
f8e0: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b elease a.** lock
f8f0: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 outside of this
f900: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e range.*/.#defin
f910: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f e SQLITE_SHM_NLO
f920: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a CK 8.../*
f930: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e .** CAPI3REF: In
f940: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c itialize The SQL
f950: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a ite Library.**.*
f960: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
f970: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
f980: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 ine initializes
f990: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 the.** SQLite li
f9a0: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c brary. ^The sql
f9b0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
f9c0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c routine.** deall
f9d0: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 ocates any resou
f9e0: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 rces that were a
f9f0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 llocated by sqli
fa00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
fa10: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 ..** These routi
fa20: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 nes are designed
fa30: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 to aid in proce
fa40: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ss initializatio
fa50: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 n and.** shutdow
fa60: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 n on embedded sy
fa70: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 stems. Workstat
fa80: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 ion applications
fa90: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 using.** SQLite
faa0: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 normally do not
fab0: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 need to invoke
fac0: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 either of these
fad0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
fae0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 A call to sqlite
faf0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
fb00: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 s an "effective"
fb10: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a call if it is.*
fb20: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 * the first time
fb30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
fb40: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
fb50: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 during the life
fb60: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 time of.** the p
fb70: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 rocess, or if it
fb80: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 is the first ti
fb90: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 me sqlite3_initi
fba0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
fbb0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ed.** following
fbc0: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 a call to sqlite
fbd0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 3_shutdown(). ^
fbe0: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 (Only an effecti
fbf0: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 ve call.** of sq
fc00: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
fc10: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 () does any init
fc20: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c ialization. All
fc30: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 other calls.**
fc40: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d are harmless no-
fc50: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 ops.)^.**.** A c
fc60: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
fc70: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 hutdown() is an
fc80: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c "effective" call
fc90: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 if it is the fi
fca0: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 rst.** call to s
fcb0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
fcc0: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 ) since the last
fcd0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
fce0: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a ize(). ^(Only.*
fcf0: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 * an effective c
fd00: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
fd10: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 hutdown() does a
fd20: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 ny deinitializat
fd30: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 ion..** All othe
fd40: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f r valid calls to
fd50: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
fd60: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 n() are harmless
fd70: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a no-ops.)^.**.**
fd80: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 The sqlite3_ini
fd90: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 tialize() interf
fda0: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 ace is threadsaf
fdb0: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 e, but sqlite3_s
fdc0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 hutdown().** is
fdd0: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 not. The sqlite
fde0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 3_shutdown() int
fdf0: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 erface must only
fe00: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
fe10: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 a.** single thre
fe20: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 ad. All open [d
fe30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
fe40: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f ons] must be clo
fe50: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f sed and all.** o
fe60: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f ther SQLite reso
fe70: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 urces must be de
fe80: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 allocated prior
fe90: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 to invoking.** s
fea0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
feb0: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f )..**.** Among o
fec0: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 ther things, ^sq
fed0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
fee0: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a () will invoke.*
fef0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 * sqlite3_os_ini
ff00: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c t(). Similarly,
ff10: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f ^sqlite3_shutdo
ff20: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 wn().** will inv
ff30: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 oke sqlite3_os_e
ff40: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 nd()..**.** ^The
ff50: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
ff60: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 ize() routine re
ff70: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
ff80: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a ] on success..**
ff90: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 ^If for some re
ffa0: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e ason, sqlite3_in
ffb0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e itialize() is un
ffc0: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 able to initiali
ffd0: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 ze.** the librar
ffe0: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 y (perhaps it is
fff0: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
10000 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 ate a needed res
10010 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 ource such.** as
10020 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 a mutex) it ret
10030 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 urns an [error c
10040 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 ode] other than
10050 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a [SQLITE_OK]..**.
10060 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
10070 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
10080 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 tine is called i
10090 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e nternally by man
100a0 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 y other.** SQLit
100b0 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 e interfaces so
100c0 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 that an applicat
100d0 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 ion usually does
100e0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 not need to.**
100f0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 invoke sqlite3_i
10100 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 nitialize() dire
10110 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 ctly. For examp
10120 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 le, [sqlite3_ope
10130 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 n()].** calls sq
10140 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
10150 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 () so the SQLite
10160 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 library will be
10170 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a automatically.*
10180 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 * initialized wh
10190 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e en [sqlite3_open
101a0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 ()] is called if
101b0 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 it has not be i
101c0 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c nitialized.** al
101d0 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 ready. ^However
101e0 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 , if SQLite is c
101f0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
10200 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 [SQLITE_OMIT_AU
10210 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 TOINIT].** compi
10220 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 le-time option,
10230 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 then the automat
10240 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ic calls to sqli
10250 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
10260 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 .** are omitted
10270 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 and the applicat
10280 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 ion must call sq
10290 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
102a0 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 () directly.** p
102b0 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e rior to using an
102c0 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 y other SQLite i
102d0 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d nterface. For m
102e0 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 aximum portabili
102f0 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 ty,.** it is rec
10300 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 ommended that ap
10310 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 plications alway
10320 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 s invoke sqlite3
10330 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a _initialize().**
10340 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 directly prior
10350 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 to using any oth
10360 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
10370 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c ace. Future rel
10380 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 eases.** of SQLi
10390 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 te may require t
103a0 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 his. In other w
103b0 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 ords, the behavi
103c0 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 or exhibited.**
103d0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
103e0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 ompiled with [SQ
103f0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e LITE_OMIT_AUTOIN
10400 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 IT] might become
10410 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 the.** default
10420 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 behavior in some
10430 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 future release
10440 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
10450 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
10460 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 init() routine d
10470 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 oes operating-sy
10480 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a stem specific.**
10490 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
104a0 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 of the SQLite li
104b0 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 brary. The sqli
104c0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
104d0 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 routine undoes t
104e0 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c he effect of sql
104f0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 ite3_os_init().
10500 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a Typical tasks.*
10510 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 * performed by t
10520 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e hese routines in
10530 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e clude allocation
10540 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e or deallocation
10550 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 .** of static re
10560 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c sources, initial
10570 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 ization of globa
10580 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 l variables,.**
10590 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 setting up a def
105a0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
105b0 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 s] module, or se
105c0 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 tting up.** a de
105d0 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 fault configurat
105e0 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ion using [sqlit
105f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a e3_config()]..**
10600 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
10610 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
10620 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 invoke either s
10630 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
10640 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f .** or sqlite3_o
10650 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 s_end() directly
10660 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 . The applicati
10670 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 on should only i
10680 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
10690 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e _initialize() an
106a0 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f d sqlite3_shutdo
106b0 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 wn(). The sqlit
106c0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 e3_os_init().**
106d0 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c interface is cal
106e0 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c led automaticall
106f0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 y by sqlite3_ini
10700 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a tialize() and.**
10710 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
10720 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 ) is called by s
10730 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
10740 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a ). Appropriate.
10750 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
10760 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f ns for sqlite3_o
10770 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c s_init() and sql
10780 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
10790 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 are built into
107a0 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 SQLite when it i
107b0 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 s compiled for U
107c0 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 nix, Windows, or
107d0 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b OS/2..** When [
107e0 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 custom builds |
107f0 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 built for other
10800 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 platforms].** (u
10810 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 sing the [SQLITE
10820 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d _OS_OTHER=1] com
10830 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 pile-time.** opt
10840 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 ion) the applica
10850 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 tion must supply
10860 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c a suitable impl
10870 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a ementation for.*
10880 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 * sqlite3_os_ini
10890 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t() and sqlite3_
108a0 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 os_end(). An ap
108b0 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 plication-suppli
108c0 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 ed.** implementa
108d0 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f tion of sqlite3_
108e0 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c os_init() or sql
108f0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
10900 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 must return [SQ
10910 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
10920 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 ess and some oth
10930 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 er [error code]
10940 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e upon.** failure.
10950 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
10960 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 initialize(void)
10970 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 ;.int sqlite3_sh
10980 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e utdown(void);.in
10990 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 t sqlite3_os_ini
109a0 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c t(void);.int sql
109b0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 ite3_os_end(void
109c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
109d0 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 EF: Configuring
109e0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 The SQLite Libra
109f0 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ry.**.** The sql
10a00 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e ite3_config() in
10a10 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
10a20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 to make global c
10a30 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 onfiguration.**
10a40 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 changes to SQLit
10a50 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 e in order to tu
10a60 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 ne SQLite to the
10a70 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 specific needs
10a80 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 of.** the applic
10a90 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 ation. The defa
10aa0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
10ab0 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 n is recommended
10ac0 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 for most.** app
10ad0 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f lications and so
10ae0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
10af0 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 usually not nec
10b00 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a essary. It is.*
10b10 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 * provided to su
10b20 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 pport rare appli
10b30 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 cations with unu
10b40 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a sual needs..**.*
10b50 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33 * <b>The sqlite3
10b60 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 _config() interf
10b70 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 ace is not threa
10b80 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69 dsafe. The appli
10b90 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 cation.** must e
10ba0 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 nsure that no ot
10bb0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
10bc0 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 faces are invoke
10bd0 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 d by other.** th
10be0 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 reads while sqli
10bf0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 te3_config() is
10c00 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a running.</b>.**.
10c10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
10c20 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
10c30 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 e.** may only be
10c40 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 invoked prior t
10c50 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 o library initia
10c60 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a lization using.*
10c70 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 * [sqlite3_initi
10c80 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 alize()] or afte
10c90 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 r shutdown by [s
10ca0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
10cb0 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 )]..** ^If sqlit
10cc0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 e3_config() is c
10cd0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c alled after [sql
10ce0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
10cf0 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a )] and before.**
10d00 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
10d10 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 wn()] then it wi
10d20 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 ll return SQLITE
10d30 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 _MISUSE..** Note
10d40 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 , however, that
10d50 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 ^sqlite3_config(
10d60 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 ) can be called
10d70 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a as part of the.*
10d80 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
10d90 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 of an applicati
10da0 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 on-defined [sqli
10db0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a te3_os_init()]..
10dc0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
10dd0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
10de0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 te3_config() is
10df0 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 an integer.** [c
10e00 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
10e10 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d ion] that determ
10e20 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f ines.** what pro
10e30 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 perty of SQLite
10e40 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 is to be configu
10e50 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 red. Subsequent
10e60 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 arguments.** va
10e70 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 ry depending on
10e80 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 the [configurati
10e90 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e on option].** in
10ea0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
10eb0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e ent..**.** ^When
10ec0 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e a configuration
10ed0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 option is set,
10ee0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
10ef0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
10f00 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 _OK]..** ^If the
10f10 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f option is unkno
10f20 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 wn or SQLite is
10f30 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 unable to set th
10f40 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e e option.** then
10f50 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 this routine re
10f60 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f turns a non-zero
10f70 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a [error code]..*
10f80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f /.int sqlite3_co
10f90 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a nfig(int, ...);.
10fa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
10fb0 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 Configure datab
10fc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a ase connections.
10fd0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
10fe0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e3.**.** The sql
10ff0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
11000 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
11010 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 ed to make confi
11020 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e guration.** chan
11030 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 ges to a [databa
11040 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
11050 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 The interface i
11060 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 s similar to.**
11070 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
11080 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 )] except that t
11090 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 he changes apply
110a0 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 to a single.**
110b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
110c0 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 tion] (specified
110d0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
110e0 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 gument)..**.** T
110f0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
11100 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 nt to sqlite3_db
11110 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 _config(D,V,...)
11120 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c is the.** [SQL
11130 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
11140 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 KASIDE | configu
11150 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 ration verb] - a
11160 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a n integer code .
11170 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 ** that indicate
11180 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 s what aspect of
11190 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
111a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 onnection] is be
111b0 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a ing configured..
111c0 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 ** Subsequent ar
111d0 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 guments vary dep
111e0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f ending on the co
111f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 nfiguration verb
11200 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 ..**.** ^Calls t
11210 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e o sqlite3_db_con
11220 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c fig() return SQL
11230 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e ITE_OK if and on
11240 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c ly if.** the cal
11250 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 l is considered
11260 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 successful..*/.i
11270 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f nt sqlite3_db_co
11280 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 nfig(sqlite3*, i
11290 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a nt op, ...);../*
112a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
112b0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 mory Allocation
112c0 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 Routines.**.** A
112d0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
112e0 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 is object define
112f0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 s the interface
11300 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a between SQLite.*
11310 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 * and low-level
11320 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
11330 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a n routines..**.*
11340 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 * This object is
11350 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e used in only on
11360 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 e place in the S
11370 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
11380 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f .** A pointer to
11390 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
113a0 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 this object is t
113b0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a he argument to.*
113c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
113d0 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f g()] when the co
113e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
113f0 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 on is.** [SQLITE
11400 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 _CONFIG_MALLOC]
11410 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 or [SQLITE_CONFI
11420 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a G_GETMALLOC]. .
11430 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 ** By creating a
11440 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
11450 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 is object.** and
11460 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b passing it to [
11470 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
11480 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
11490 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e ALLOC]).** durin
114a0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c g configuration,
114b0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
114c0 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 can specify an a
114d0 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 lternative.** me
114e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
114f0 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 subsystem for SQ
11500 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 Lite to use for
11510 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 all of its.** dy
11520 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 namic memory nee
11530 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 ds..**.** Note t
11540 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 hat SQLite comes
11550 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 with several [b
11560 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
11570 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 llocators].** th
11580 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 at are perfectly
11590 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 adequate for th
115a0 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d e overwhelming m
115b0 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 ajority of appli
115c0 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 cations.** and t
115d0 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 hat this object
115e0 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 is only useful t
115f0 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 o a tiny minorit
11600 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e y of application
11610 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 s.** with specia
11620 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c lized memory all
11630 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d ocation requirem
11640 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 ents. This obje
11650 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 ct is.** also us
11660 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
11670 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f g of SQLite in o
11680 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 rder to specify
11690 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a an alternative.*
116a0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
116b0 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 or that simulate
116c0 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d s memory out-of-
116d0 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e memory condition
116e0 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f s in.** order to
116f0 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c verify that SQL
11700 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 ite recovers gra
11710 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 cefully from suc
11720 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e h.** conditions.
11730 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c .**.** The xMall
11740 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e oc, xRealloc, an
11750 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 d xFree methods
11760 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 must work like t
11770 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 he.** malloc(),
11780 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 realloc() and fr
11790 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 ee() functions f
117a0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 rom the standard
117b0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e C library..** ^
117c0 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 SQLite guarantee
117d0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e s that the secon
117e0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
117f0 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 xRealloc is alw
11800 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 ays a value retu
11810 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 rned by a prior
11820 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 call to xRoundup
11830 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 ..**.** xSize sh
11840 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 ould return the
11850 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f allocated size o
11860 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
11870 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 ation.** previou
11880 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f sly obtained fro
11890 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 m xMalloc or xRe
118a0 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f alloc. The allo
118b0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 cated size.** is
118c0 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 always at least
118d0 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 as big as the r
118e0 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 equested size bu
118f0 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e t may be larger.
11900 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e .**.** The xRoun
11910 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 dup method retur
11920 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 ns what would be
11930 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 the allocated s
11940 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f ize of.** a memo
11950 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 ry allocation gi
11960 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 ven a particular
11970 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e requested size.
11980 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a Most memory.**
11990 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e allocators roun
119a0 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f d up memory allo
119b0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 cations at least
119c0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c to the next mul
119d0 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 tiple.** of 8.
119e0 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 Some allocators
119f0 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 round up to a la
11a00 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 rger multiple or
11a10 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 to a power of 2
11a20 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 ..** Every memor
11a30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 y allocation req
11a40 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 uest coming in t
11a50 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f hrough [sqlite3_
11a60 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 malloc()].** or
11a70 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
11a80 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 ()] first calls
11a90 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 xRoundup. If xR
11aa0 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 oundup returns 0
11ab0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 , .** that cause
11ac0 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 s the correspond
11ad0 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ing memory alloc
11ae0 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a ation to fail..*
11af0 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d *.** The xInit m
11b00 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 ethod initialize
11b10 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c s the memory all
11b20 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 ocator. For exa
11b30 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 mple,.** it migh
11b40 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 t allocate any r
11b50 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f equire mutexes o
11b60 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 r initialize int
11b70 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 ernal data.** st
11b80 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 ructures. The x
11b90 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 Shutdown method
11ba0 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 is invoked (indi
11bb0 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 rectly) by.** [s
11bc0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
11bd0 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 )] and should de
11be0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 allocate any res
11bf0 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a ources acquired.
11c00 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 ** by xInit. Th
11c10 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 e pAppData point
11c20 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 er is used as th
11c30 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 e only parameter
11c40 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 to.** xInit and
11c50 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a xShutdown..**.*
11c60 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 * SQLite holds t
11c70 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 he [SQLITE_MUTEX
11c80 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 _STATIC_MASTER]
11c90 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e mutex when it in
11ca0 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e vokes.** the xIn
11cb0 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 it method, so th
11cc0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e e xInit method n
11cd0 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 eed not be threa
11ce0 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 dsafe. The.** x
11cf0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 Shutdown method
11d00 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 is only called f
11d10 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 rom [sqlite3_shu
11d20 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 tdown()] so it d
11d30 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 oes.** not need
11d40 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 to be threadsafe
11d50 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c either. For al
11d60 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c l other methods,
11d70 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 SQLite.** holds
11d80 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 the [SQLITE_MUT
11d90 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d EX_STATIC_MEM] m
11da0 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 utex as long as
11db0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 the.** [SQLITE_C
11dc0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d ONFIG_MEMSTATUS]
11dd0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
11de0 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 ption is turned
11df0 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 on (which.** it
11e00 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 is by default) a
11e10 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 nd so the method
11e20 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 s are automatica
11e30 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a lly serialized..
11e40 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b ** However, if [
11e50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
11e60 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 MSTATUS] is disa
11e70 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f bled, then the o
11e80 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 ther.** methods
11e90 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 must be threadsa
11ea0 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 fe or else make
11eb0 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 their own arrang
11ec0 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 ements for.** se
11ed0 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a rialization..**.
11ee0 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e ** SQLite will n
11ef0 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 ever invoke xIni
11f00 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e t() more than on
11f10 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e ce without an in
11f20 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c tervening.** cal
11f30 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 l to xShutdown()
11f40 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
11f50 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f uct sqlite3_mem_
11f60 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f methods sqlite3_
11f70 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 mem_methods;.str
11f80 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f uct sqlite3_mem_
11f90 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 methods {. void
11fa0 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 *(*xMalloc)(int
11fb0 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 ); /* Me
11fc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
11fd0 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f function */. vo
11fe0 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 id (*xFree)(void
11ff0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 *); /*
12000 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c Free a prior all
12010 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 ocation */. voi
12020 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 d *(*xRealloc)(v
12030 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 oid*,int); /* R
12040 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 esize an allocat
12050 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ion */. int (*x
12060 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 Size)(void*);
12070 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 /* Retur
12080 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e n the size of an
12090 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
120a0 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 int (*xRoundup)
120b0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 (int);
120c0 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 /* Round up requ
120d0 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f est size to allo
120e0 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 cation size */.
120f0 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f int (*xInit)(vo
12100 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 id*);
12110 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 /* Initialize th
12120 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
12130 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 or */. void (*x
12140 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 Shutdown)(void*)
12150 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 ; /* Deinit
12160 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 ialize the memor
12170 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 y allocator */.
12180 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b void *pAppData;
12190 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
121a0 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 /* Argument to x
121b0 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 Init() and xShut
121c0 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a down() */.};../*
121d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
121e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 nfiguration Opti
121f0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ons.** KEYWORDS:
12200 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 {configuration
12210 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 option}.**.** Th
12220 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
12230 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 e the available
12240 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 integer configur
12250 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 ation options th
12260 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 at.** can be pas
12270 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 sed as the first
12280 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
12290 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
122a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
122b0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 *.** New configu
122c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
122d0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
122e0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
122f0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 f SQLite..** Exi
12300 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 sting configurat
12310 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 ion options migh
12320 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 t be discontinue
12330 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 d. Applications
12340 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b .** should check
12350 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 the return code
12360 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 from [sqlite3_c
12370 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 onfig()] to make
12380 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 sure that.** th
12390 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 e call worked.
123a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e The [sqlite3_con
123b0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
123c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a will return a.*
123d0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f * non-zero [erro
123e0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 r code] if a dis
123f0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 continued or uns
12400 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 upported configu
12410 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a ration option.**
12420 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a is invoked..**.
12430 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c ** <dl>.** [[SQL
12440 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
12450 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 ETHREAD]] <dt>SQ
12460 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
12470 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a LETHREAD</dt>.**
12480 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
12490 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
124a0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 his option. ^Th
124b0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
124c0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 he.** [threading
124d0 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 mode] to Single
124e0 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 -thread. In oth
124f0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 er words, it dis
12500 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 ables.** all mut
12510 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 exing and puts S
12520 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 QLite into a mod
12530 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f e where it can o
12540 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 nly be used.** b
12550 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 y a single threa
12560 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 d. ^If SQLite
12570 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
12580 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
12590 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
125a0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
125b0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
125c0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 ption then.** it
125d0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 is not possible
125e0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b to change the [
125f0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
12600 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 from its default
12610 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e .** value of Sin
12620 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 gle-thread and s
12630 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
12640 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e g()] will return
12650 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 .** [SQLITE_ERR
12660 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 OR] if called wi
12670 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f th the SQLITE_CO
12680 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
12690 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 D.** configurati
126a0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a on option.</dd>.
126b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
126c0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
126d0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 D]] <dt>SQLITE_C
126e0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
126f0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
12700 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d ere are no argum
12710 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 ents to this opt
12720 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 ion. ^This opti
12730 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b on sets the.** [
12740 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
12750 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e to Multi-thread.
12760 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 In other words
12770 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a , it disables.**
12780 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 mutexing on [da
12790 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
127a0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 n] and [prepared
127b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 statement] obje
127c0 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c cts..** The appl
127d0 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f ication is respo
127e0 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 nsible for seria
127f0 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f lizing access to
12800 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
12810 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b nnections] and [
12820 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
12830 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 nts]. But other
12840 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 mutexes.** are
12850 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 enabled so that
12860 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 SQLite will be s
12870 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 afe to use in a
12880 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a multi-threaded.*
12890 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 * environment as
128a0 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 long as no two
128b0 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 threads attempt
128c0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a to use the same.
128d0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
128e0 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 nection] at the
128f0 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 same time. ^If
12900 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
12910 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
12920 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
12930 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
12940 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
12950 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
12960 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 n.** it is not p
12970 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 ossible to set t
12980 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 he Multi-thread
12990 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
129a0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
129b0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 _config()] will
129c0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
129d0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 RROR] if called
129e0 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 with the.** SQLI
129f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
12a00 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 HREAD configurat
12a10 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e ion option.</dd>
12a20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
12a30 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 CONFIG_SERIALIZE
12a40 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 D]] <dt>SQLITE_C
12a50 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
12a60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
12a70 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 re are no argume
12a80 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
12a90 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f on. ^This optio
12aa0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 n sets the.** [t
12ab0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 hreading mode] t
12ac0 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e o Serialized. In
12ad0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
12ae0 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 is option enable
12af0 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 s.** all mutexes
12b00 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 including the r
12b10 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 ecursive.** mute
12b20 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 xes on [database
12b30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 connection] and
12b40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
12b50 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a ment] objects..*
12b60 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 * In this mode (
12b70 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 which is the def
12b80 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 ault when SQLite
12b90 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
12ba0 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 h.** [SQLITE_THR
12bb0 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 EADSAFE=1]) the
12bc0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 SQLite library w
12bd0 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 ill itself seria
12be0 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 lize access.** t
12bf0 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e o [database conn
12c00 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 ections] and [pr
12c10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
12c20 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a s] so that the.*
12c30 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 * application is
12c40 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 free to use the
12c50 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
12c60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 connection] or t
12c70 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 he.** same [prep
12c80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
12c90 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 in different thr
12ca0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 eads at the same
12cb0 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 time..** ^If SQ
12cc0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
12cd0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 with.** the [SQ
12ce0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 LITE_THREADSAFE
12cf0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 | SQLITE_THREADS
12d00 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 AFE=0] compile-t
12d10 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a ime option then.
12d20 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 ** it is not pos
12d30 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 sible to set the
12d40 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 Serialized [thr
12d50 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 eading mode] and
12d60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
12d70 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 fig()] will retu
12d80 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 rn [SQLITE_ERROR
12d90 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 ] if called with
12da0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 the.** SQLITE_C
12db0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
12dc0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
12dd0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ption.</dd>.**.*
12de0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
12df0 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 G_MALLOC]] <dt>S
12e00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
12e10 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LOC</dt>.** <dd>
12e20 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f ^(The SQLITE_CO
12e30 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 NFIG_MALLOC opti
12e40 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
12e50 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
12e60 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 is .** a pointe
12e70 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 r to an instance
12e80 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
12e90 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 _mem_methods] st
12ea0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 ructure..** The
12eb0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 argument specifi
12ec0 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 es.** alternativ
12ed0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f e low-level memo
12ee0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
12ef0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 utines to be use
12f00 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a d in place of.**
12f10 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
12f20 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 cation routines
12f30 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
12f40 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b e.)^ ^SQLite mak
12f50 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 es.** its own pr
12f60 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
12f70 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
12f80 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
12f90 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
12fa0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b .** before the [
12fb0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
12fc0 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c ] call returns.<
12fd0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
12fe0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
12ff0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 LLOC]] <dt>SQLIT
13000 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
13010 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 OC</dt>.** <dd>
13020 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^(The SQLITE_CON
13030 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 FIG_GETMALLOC op
13040 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
13050 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
13060 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 ch.** is a point
13070 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
13080 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 e of the [sqlite
13090 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 3_mem_methods] s
130a0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 tructure..** The
130b0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
130c0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 thods].** struct
130d0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 ure is filled wi
130e0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 th the currently
130f0 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 defined memory
13100 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
13110 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f nes.)^.** This o
13120 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 ption can be use
13130 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 d to overload th
13140 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 e default memory
13150 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 allocation.** r
13160 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 outines with a w
13170 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 rapper that simu
13180 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 lations memory a
13190 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 llocation failur
131a0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d e or.** tracks m
131b0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 emory usage, for
131c0 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a example. </dd>.
131d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
131e0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d ONFIG_MEMSTATUS]
131f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
13200 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 FIG_MEMSTATUS</d
13210 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 t>.** <dd> ^The
13220 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
13230 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 MSTATUS option t
13240 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 akes single argu
13250 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 ment of type int
13260 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 ,.** interpreted
13270 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 as a boolean, w
13280 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 hich enables or
13290 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c disables the col
132a0 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 lection of.** me
132b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
132c0 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 statistics. ^(Wh
132d0 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 en memory alloca
132e0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 tion statistics
132f0 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c are.** disabled,
13300 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 the following S
13310 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
13320 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 become non-oper
13330 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 ational:.** <u
13340 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 l>.** <li> [sq
13350 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
13360 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b d()].** <li> [
13370 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
13380 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 ighwater()].**
13390 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 <li> [sqlite3_s
133a0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 oft_heap_limit64
133b0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
133c0 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 qlite3_status64(
133d0 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a )].** </ul>)^.
133e0 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ** ^Memory alloc
133f0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 ation statistics
13400 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 are enabled by
13410 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 default unless S
13420 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 QLite is.** comp
13430 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 iled with [SQLIT
13440 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 E_DEFAULT_MEMSTA
13450 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 TUS]=0 in which
13460 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 case memory.** a
13470 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 llocation statis
13480 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 tics are disable
13490 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a d by default..**
134a0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
134b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
134c0 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 ATCH]] <dt>SQLIT
134d0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
134e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
134f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
13500 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 _SCRATCH option
13510 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 specifies a stat
13520 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 ic memory buffer
13530 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 .** that SQLite
13540 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 can use for scra
13550 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 tch memory. ^(T
13560 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
13570 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 rguments.** to S
13580 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
13590 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 ATCH: A pointer
135a0 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c an 8-byte.** al
135b0 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 igned memory buf
135c0 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 fer from which t
135d0 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 he scratch alloc
135e0 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a ations will be.*
135f0 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a * drawn, the siz
13600 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 e of each scratc
13610 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a h allocation (sz
13620 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 ),.** and the ma
13630 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
13640 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 scratch allocati
13650 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 ons (N).)^.** Th
13660 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
13670 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 must be a point
13680 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 er to an 8-byte
13690 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a aligned buffer.*
136a0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a * of at least sz
136b0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f *N bytes of memo
136c0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 ry..** ^SQLite w
136d0 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 ill not use more
136e0 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 than one scratc
136f0 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 h buffers per th
13700 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 read..** ^SQLite
13710 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 will never requ
13720 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75 est a scratch bu
13730 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 ffer that is mor
13740 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 e than 6.** time
13750 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 s the database p
13760 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 age size..** ^If
13770 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 SQLite needs ne
13780 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a eds additional.*
13790 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 * scratch memory
137a0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 beyond what is
137b0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 provided by this
137c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
137d0 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 ption, then .**
137e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
137f0 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 )] will be used
13800 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 to obtain the me
13810 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a mory needed.<p>.
13820 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 ** ^When the app
13830 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 lication provide
13840 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 s any amount of
13850 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 scratch memory u
13860 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 sing.** SQLITE_C
13870 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 ONFIG_SCRATCH, S
13880 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e QLite avoids unn
13890 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a ecessary large.*
138a0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f * [sqlite3_mallo
138b0 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f c|heap allocatio
138c0 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e ns]..** This can
138d0 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 help [Robson pr
138e0 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f oof|prevent memo
138f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 ry allocation fa
13900 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 ilures] due to h
13910 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 eap.** fragmenta
13920 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f tion in low-memo
13930 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 ry embedded syst
13940 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a ems..** </dd>.**
13950 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
13960 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 FIG_PAGECACHE]]
13970 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
13980 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e G_PAGECACHE</dt>
13990 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 .** <dd> ^The SQ
139a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
139b0 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 CACHE option spe
139c0 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 cifies a memory
139d0 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c pool.** that SQL
139e0 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 ite can use for
139f0 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 the database pag
13a00 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 e cache with the
13a10 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a default page.**
13a20 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 cache implement
13a30 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 ation. .** This
13a40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
13a50 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 ption is a no-op
13a60 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 if an applicati
13a70 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a on-define page.*
13a80 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e * cache implemen
13a90 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 tation is loaded
13aa0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 using the [SQLI
13ab0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
13ac0 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 2]..** ^There ar
13ad0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 e three argument
13ae0 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 s to SQLITE_CONF
13af0 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20 IG_PAGECACHE: A
13b00 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d pointer to.** 8-
13b10 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d byte aligned mem
13b20 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 ory (pMem), the
13b30 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 size of each pag
13b40 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a e cache line (sz
13b50 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 ),.** and the nu
13b60 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69 mber of cache li
13b70 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 nes (N)..** The
13b80 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 sz argument shou
13b90 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f ld be the size o
13ba0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 f the largest da
13bb0 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 tabase page.** (
13bc0 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 a power of two b
13bd0 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36 etween 512 and 6
13be0 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 5536) plus some
13bf0 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 extra bytes for
13c00 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 each.** page hea
13c10 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 der. ^The numbe
13c20 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 r of extra bytes
13c30 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70 needed by the p
13c40 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 age header.** ca
13c50 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 n be determined
13c60 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f using [SQLITE_CO
13c70 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 NFIG_PCACHE_HDRS
13c80 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 Z]..** ^It is ha
13c90 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 rmless, apart fr
13ca0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 om the wasted me
13cb0 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 mory,.** for the
13cc0 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f sz parameter to
13cd0 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 be larger than
13ce0 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20 necessary. The
13cf0 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 pMem.** argument
13d00 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 must be either
13d10 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f a NULL pointer o
13d20 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 r a pointer to a
13d30 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 n 8-byte.** alig
13d40 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d ned block of mem
13d50 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 ory of at least
13d60 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 sz*N bytes, othe
13d70 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 rwise.** subsequ
13d80 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 ent behavior is
13d90 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 undefined..** ^W
13da0 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 hen pMem is not
13db0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c NULL, SQLite wil
13dc0 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65 20 l strive to use
13dd0 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 the memory provi
13de0 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 ded.** to satisf
13df0 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65 65 y page cache nee
13e00 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b ds, falling back
13e10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c to [sqlite3_mal
13e20 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 loc()] if.** a p
13e30 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69 age cache line i
13e40 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a s larger than sz
13e50 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c bytes or if all
13e60 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66 of the pMem buf
13e70 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 fer.** is exhaus
13e80 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d ted..** ^If pMem
13e90 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 is NULL and N i
13ea0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e s non-zero, then
13eb0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 each database c
13ec0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 onnection.** doe
13ed0 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c s an initial bul
13ee0 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 k allocation for
13ef0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f page cache memo
13f00 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 ry.** from [sqli
13f10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 te3_malloc()] su
13f20 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 fficient for N c
13f30 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 ache lines if N
13f40 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a is positive or.*
13f50 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 * of -1024*N byt
13f60 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 es if N is negat
13f70 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 ive, . ^If addit
13f80 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 ional.** page ca
13f90 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 che memory is ne
13fa0 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 eded beyond what
13fb0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 is provided by
13fc0 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 the initial.** a
13fd0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 llocation, then
13fe0 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b SQLite goes to [
13ff0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
14000 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72 ] separately for
14010 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f each.** additio
14020 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 nal cache line.
14030 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
14040 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
14050 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
14060 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a NFIG_HEAP</dt>.*
14070 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 * <dd> ^The SQLI
14080 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f TE_CONFIG_HEAP o
14090 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 ption specifies
140a0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 a static memory
140b0 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 buffer .** that
140c0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 SQLite will use
140d0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 for all of its d
140e0 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c ynamic memory al
140f0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a location needs.*
14100 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 * beyond those p
14110 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b rovided for by [
14120 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
14130 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 RATCH] and.** [S
14140 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
14150 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 ECACHE]..** ^The
14160 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 SQLITE_CONFIG_H
14170 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e EAP option is on
14180 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 ly available if
14190 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
141a0 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 ed.** with eithe
141b0 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 r [SQLITE_ENABLE
141c0 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 _MEMSYS3] or [SQ
141d0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 LITE_ENABLE_MEMS
141e0 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 YS5] and returns
141f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f .** [SQLITE_ERRO
14200 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 R] if invoked ot
14210 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 herwise..** ^The
14220 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
14230 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 uments to SQLITE
14240 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a _CONFIG_HEAP:.**
14250 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e An 8-byte align
14260 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 ed pointer to th
14270 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 e memory,.** the
14280 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
14290 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 in the memory b
142a0 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d uffer, and the m
142b0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f inimum allocatio
142c0 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 n size..** ^If t
142d0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 he first pointer
142e0 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 (the memory poi
142f0 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 nter) is NULL, t
14300 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 hen SQLite rever
14310 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 ts.** to using i
14320 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 ts default memor
14330 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 y allocator (the
14340 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 system malloc()
14350 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 implementation)
14360 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 ,.** undoing any
14370 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f prior invocatio
14380 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e n of [SQLITE_CON
14390 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 FIG_MALLOC]. ^I
143a0 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 f the.** memory
143b0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e pointer is not N
143c0 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 ULL then the alt
143d0 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a ernative memory.
143e0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 ** allocator is
143f0 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c engaged to handl
14400 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 e all of SQLites
14410 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
14420 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 on needs..** The
14430 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 first pointer (
14440 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 the memory point
14450 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 er) must be alig
14460 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 ned to an 8-byte
14470 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 .** boundary or
14480 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 subsequent behav
14490 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 ior of SQLite wi
144a0 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e ll be undefined.
144b0 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 .** The minimum
144c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 allocation size
144d0 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a is capped at 2**
144e0 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 12. Reasonable v
144f0 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 alues.** for the
14500 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 minimum allocat
14510 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a ion size are 2**
14520 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 5 through 2**8.<
14530 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
14540 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
14550 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
14560 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a NFIG_MUTEX</dt>.
14570 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
14580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
14590 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 X option takes a
145a0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
145b0 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 which is a.** p
145c0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
145d0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 tance of the [sq
145e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
145f0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a ods] structure..
14600 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 ** The argument
14610 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e specifies altern
14620 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 ative low-level
14630 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 mutex routines t
14640 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 o be used.** in
14650 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 place the mutex
14660 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 routines built i
14670 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e nto SQLite.)^ ^
14680 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 SQLite makes a c
14690 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f opy of.** the co
146a0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 ntent of the [sq
146b0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
146c0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 ods] structure b
146d0 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 efore the call t
146e0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
146f0 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e nfig()] returns.
14700 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
14710 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
14720 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
14730 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
14740 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
14750 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
14760 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e n then.** the en
14770 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 tire mutexing su
14780 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 bsystem is omitt
14790 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c ed from the buil
147a0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c d and hence call
147b0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s to.** [sqlite3
147c0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 _config()] with
147d0 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 the SQLITE_CONFI
147e0 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 G_MUTEX configur
147f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c ation option wil
14800 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c l.** return [SQL
14810 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e ITE_ERROR].</dd>
14820 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
14830 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d CONFIG_GETMUTEX]
14840 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
14850 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 FIG_GETMUTEX</dt
14860 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 >.** <dd> ^(The
14870 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
14880 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 TMUTEX option ta
14890 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
148a0 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 ument which.** i
148b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
148c0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
148d0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
148e0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
148f0 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 ure. The.** [sq
14900 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
14910 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 ods].** structur
14920 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 e is filled with
14930 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 the currently d
14940 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 efined mutex rou
14950 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 tines.)^.** This
14960 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 option can be u
14970 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 sed to overload
14980 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 the default mute
14990 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 x allocation.**
149a0 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 routines with a
149b0 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 wrapper used to
149c0 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 track mutex usag
149d0 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 e for performanc
149e0 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f e.** profiling o
149f0 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 r testing, for e
14a00 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 xample. ^If SQ
14a10 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
14a20 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 with.** the [SQ
14a30 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 LITE_THREADSAFE
14a40 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 | SQLITE_THREADS
14a50 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 AFE=0] compile-t
14a60 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a ime option then.
14a70 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 ** the entire mu
14a80 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d texing subsystem
14a90 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d is omitted from
14aa0 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 the build and h
14ab0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a ence calls to.**
14ac0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
14ad0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c ()] with the SQL
14ae0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
14af0 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f TEX configuratio
14b00 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a n option will.**
14b10 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
14b20 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a ERROR].</dd>.**.
14b30 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
14b40 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c IG_LOOKASIDE]] <
14b50 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
14b60 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a _LOOKASIDE</dt>.
14b70 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
14b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
14b90 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b ASIDE option tak
14ba0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 es two arguments
14bb0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a that determine.
14bc0 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 ** the default s
14bd0 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 ize of lookaside
14be0 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 memory on each
14bf0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
14c00 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 tion]..** The fi
14c10 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
14c20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 the.** size of e
14c30 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 ach lookaside bu
14c40 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 ffer slot and th
14c50 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 e second is the
14c60 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f number of.** slo
14c70 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 ts allocated to
14c80 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f each database co
14c90 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 nnection.)^ ^(S
14ca0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f QLITE_CONFIG_LOO
14cb0 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 KASIDE.** sets t
14cc0 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 he <i>default</i
14cd0 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 > lookaside size
14ce0 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 . The [SQLITE_DB
14cf0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
14d00 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b ].** option to [
14d10 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
14d20 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 g()] can be used
14d30 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c to change the l
14d40 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 ookaside.** conf
14d50 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 iguration on ind
14d60 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 ividual connecti
14d70 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a ons.)^ </dd>.**.
14d80 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
14d90 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 IG_PCACHE2]] <dt
14da0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 >SQLITE_CONFIG_P
14db0 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c CACHE2</dt>.** <
14dc0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 dd> ^(The SQLITE
14dd0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 _CONFIG_PCACHE2
14de0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
14df0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
14e00 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f hich is .** a po
14e10 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c inter to an [sql
14e20 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
14e30 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 ods2] object. T
14e40 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 his object speci
14e50 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 fies.** the inte
14e60 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f rface to a custo
14e70 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 m page cache imp
14e80 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a lementation.)^.*
14e90 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 * ^SQLite makes
14ea0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 a copy of the [s
14eb0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
14ec0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c thods2] object.<
14ed0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
14ee0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
14ef0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 ACHE2]] <dt>SQLI
14f00 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
14f10 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 CHE2</dt>.** <dd
14f20 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 > ^(The SQLITE_C
14f30 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 ONFIG_GETPCACHE2
14f40 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
14f50 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
14f60 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f which.** is a po
14f70 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c inter to an [sql
14f80 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
14f90 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 ods2] object. S
14fa0 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a QLite copies of.
14fb0 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 ** the current p
14fc0 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d age cache implem
14fd0 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 entation into th
14fe0 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 at object.)^ </d
14ff0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
15000 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c E_CONFIG_LOG]] <
15010 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
15020 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 _LOG</dt>.** <dd
15030 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e > The SQLITE_CON
15040 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 FIG_LOG option i
15050 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 s used to config
15060 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a ure the SQLite.*
15070 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 * global [error
15080 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 log]..** (^The S
15090 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
150a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 option takes tw
150b0 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 o arguments: a p
150c0 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 ointer to a.** f
150d0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 unction with a c
150e0 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 all signature of
150f0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 void(*)(void*,i
15100 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c nt,const char*),
15110 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 .** and a point
15120 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 er to void. ^If
15130 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 the function poi
15140 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c nter is not NULL
15150 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b , it is.** invok
15160 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c ed by [sqlite3_l
15170 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 og()] to process
15180 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 each logging ev
15190 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a ent. ^If the.**
151a0 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 function pointe
151b0 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b r is NULL, the [
151c0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 sqlite3_log()] i
151d0 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 nterface becomes
151e0 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 a no-op..** ^Th
151f0 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 e void pointer t
15200 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e hat is the secon
15210 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 d argument to SQ
15220 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 LITE_CONFIG_LOG
15230 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 is.** passed thr
15240 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 ough as the firs
15250 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 t parameter to t
15260 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
15270 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a efined logger.**
15280 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 function whenev
15290 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e er that function
152a0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 is invoked. ^T
152b0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
152c0 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f ter to.** the lo
152d0 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 gger function is
152e0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 a copy of the f
152f0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
15300 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 o the correspond
15310 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
15320 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 log()] call and
15330 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 is intended to b
15340 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 e a [result code
15350 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 ] or an.** [exte
15360 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
15370 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 ]. ^The third p
15380 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 arameter passed
15390 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 to the logger is
153a0 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 .** log message
153b0 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 after formatting
153c0 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e via [sqlite3_sn
153d0 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 printf()]..** Th
153e0 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 e SQLite logging
153f0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f interface is no
15400 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 t reentrant; the
15410 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e logger function
15420 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 .** supplied by
15430 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
15440 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 must not invoke
15450 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 any SQLite inter
15460 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 face..** In a mu
15470 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 lti-threaded app
15480 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 lication, the ap
15490 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
154a0 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 d logger.** func
154b0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 tion must be thr
154c0 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a eadsafe. </dd>.*
154d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
154e0 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 NFIG_URI]] <dt>S
154f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 QLITE_CONFIG_URI
15500 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 .** <dd>^(The SQ
15510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 LITE_CONFIG_URI
15520 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
15530 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f ingle argument o
15540 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 f type int..** I
15550 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e f non-zero, then
15560 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 URI handling is
15570 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 globally enable
15580 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 d. If the parame
15590 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 ter is zero,.**
155a0 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e then URI handlin
155b0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 g is globally di
155c0 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 sabled.)^ ^If UR
155d0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c I handling is gl
155e0 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 obally.** enable
155f0 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 d, all filenames
15600 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 passed to [sqli
15610 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
15620 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
15630 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ,.** [sqlite3_op
15640 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 en16()] or.** sp
15650 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 ecified as part
15660 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d of [ATTACH] comm
15670 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 ands are interpr
15680 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 eted as URIs, re
15690 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 gardless.** of w
156a0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
156b0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 e [SQLITE_OPEN_U
156c0 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 RI] flag is set
156d0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 when the databas
156e0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e.** connection
156f0 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 is opened. ^If i
15700 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 t is globally di
15710 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 sabled, filename
15720 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e s are.** only in
15730 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 terpreted as URI
15740 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f s if the SQLITE_
15750 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 OPEN_URI flag is
15760 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a set when the.**
15770 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
15780 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 tion is opened.
15790 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 ^(By default, UR
157a0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c I handling is gl
157b0 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c obally.** disabl
157c0 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 ed. The default
157d0 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 value may be cha
157e0 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e nged by compilin
157f0 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 g with the.** [S
15800 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 QLITE_USE_URI] s
15810 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e ymbol defined.)^
15820 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
15830 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f CONFIG_COVERING_
15840 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 INDEX_SCAN]] <dt
15850 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 >SQLITE_CONFIG_C
15860 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 OVERING_INDEX_SC
15870 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 AN.** <dd>^The S
15880 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 QLITE_CONFIG_COV
15890 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e ERING_INDEX_SCAN
158a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
158b0 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a single integer.*
158c0 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 * argument which
158d0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
158e0 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 as a boolean in
158f0 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 order to enable
15900 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 or disable.** th
15910 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e e use of coverin
15920 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 g indices for fu
15930 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 ll table scans i
15940 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 n the query opti
15950 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 mizer..** ^The d
15960 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 efault setting i
15970 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 s determined.**
15980 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 by the [SQLITE_A
15990 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e LLOW_COVERING_IN
159a0 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c DEX_SCAN] compil
159b0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f e-time option, o
159c0 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 r is "on".** if
159d0 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d that compile-tim
159e0 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 e option is omit
159f0 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c ted..** The abil
15a00 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 ity to disable t
15a10 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 he use of coveri
15a20 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 ng indices for f
15a30 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a ull table scans.
15a40 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f ** is because so
15a50 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 me incorrectly c
15a60 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c oded legacy appl
15a70 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d ications might m
15a80 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 alfunction.** wh
15a90 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 en the optimizat
15aa0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 ion is enabled.
15ab0 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 Providing the a
15ac0 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 bility to.** dis
15ad0 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a able the optimiz
15ae0 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 ation allows the
15af0 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 older, buggy ap
15b00 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 plication code t
15b10 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 o work.** withou
15b20 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 t change even wi
15b30 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e th newer version
15b40 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a s of SQLite..**.
15b50 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
15b60 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 IG_PCACHE]] [[SQ
15b70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
15b80 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 CACHE]].** <dt>S
15b90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
15ba0 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 CHE and SQLITE_C
15bb0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a ONFIG_GETPCACHE.
15bc0 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 ** <dd> These op
15bd0 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 tions are obsole
15be0 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f te and should no
15bf0 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 t be used by new
15c00 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 code..** They a
15c10 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 re retained for
15c20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
15c30 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 ibility but are
15c40 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c now no-ops..** <
15c50 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
15c60 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f ITE_CONFIG_SQLLO
15c70 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 G]].** <dt>SQLIT
15c80 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a E_CONFIG_SQLLOG.
15c90 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 ** <dd>This opti
15ca0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c on is only avail
15cb0 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 able if sqlite i
15cc0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
15cd0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 the.** [SQLITE_E
15ce0 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 NABLE_SQLLOG] pr
15cf0 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 e-processor macr
15d00 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 o defined. The f
15d10 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 irst argument sh
15d20 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 ould.** be a poi
15d30 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 nter to a functi
15d40 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 on of type void(
15d50 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 *)(void*,sqlite3
15d60 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 *,const char*, i
15d70 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f nt)..** The seco
15d80 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 nd should be of
15d90 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 type (void*). Th
15da0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e e callback is in
15db0 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 voked by the lib
15dc0 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 rary.** in three
15dd0 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d separate circum
15de0 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 stances, identif
15df0 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 ied by the value
15e00 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a passed as the.*
15e10 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 * fourth paramet
15e20 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 er. If the fourt
15e30 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 h parameter is 0
15e40 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 , then the datab
15e50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
15e60 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 * passed as the
15e70 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
15e80 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 has just been op
15e90 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 ened. The third
15ea0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e argument.** poin
15eb0 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 ts to a buffer c
15ec0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 ontaining the na
15ed0 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 me of the main d
15ee0 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 atabase file. If
15ef0 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 the.** fourth p
15f00 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 arameter is 1, t
15f10 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 hen the SQL stat
15f20 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 ement that the t
15f30 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a hird parameter.*
15f40 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 * points to has
15f50 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 just been execut
15f60 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 ed. Or, if the f
15f70 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
15f80 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 is 2, then.** th
15f90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 e connection bei
15fa0 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 ng passed as the
15fb0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
15fc0 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 r is being close
15fd0 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 d. The.** third
15fe0 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 parameter is pas
15ff0 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 sed NULL In this
16000 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 case. An examp
16010 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 le of using this
16020 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f .** configuratio
16030 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 n option can be
16040 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 seen in the "tes
16050 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 t_sqllog.c" sour
16060 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 ce file in.** th
16070 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 e canonical SQLi
16080 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c te source tree.<
16090 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
160a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f ITE_CONFIG_MMAP_
160b0 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 SIZE]].** <dt>SQ
160c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 LITE_CONFIG_MMAP
160d0 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 _SIZE.** <dd>^SQ
160e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 LITE_CONFIG_MMAP
160f0 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 _SIZE takes two
16100 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 64-bit integer (
16110 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 sqlite3_int64) v
16120 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 alues.** that ar
16130 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d e the default mm
16140 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 ap size limit (t
16150 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 he default setti
16160 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d ng for.** [PRAGM
16170 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e A mmap_size]) an
16180 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c d the maximum al
16190 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 lowed mmap size
161a0 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 limit..** ^The d
161b0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 efault setting c
161c0 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e an be overridden
161d0 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73 by each databas
161e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 e connection usi
161f0 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 ng.** either the
16200 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 [PRAGMA mmap_si
16210 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 ze] command, or
16220 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 by using the.**
16230 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d [SQLITE_FCNTL_MM
16240 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f AP_SIZE] file co
16250 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 ntrol. ^(The ma
16260 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d ximum allowed mm
16270 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 ap size.** will
16280 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e be silently trun
16290 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 cated if necessa
162a0 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f ry so that it do
162b0 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 es not exceed th
162c0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d e.** compile-tim
162d0 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 e maximum mmap s
162e0 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a ize set by the.*
162f0 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d * [SQLITE_MAX_MM
16300 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 AP_SIZE] compile
16310 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a -time option.)^.
16320 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 ** ^If either ar
16330 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f gument to this o
16340 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 ption is negativ
16350 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 e, then that arg
16360 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e ument is.** chan
16370 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 ged to its compi
16380 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e le-time default.
16390 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
163a0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 CONFIG_WIN32_HEA
163b0 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 PSIZE]].** <dt>S
163c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e QLITE_CONFIG_WIN
163d0 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 32_HEAPSIZE.** <
163e0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 dd>^The SQLITE_C
163f0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 ONFIG_WIN32_HEAP
16400 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f SIZE option is o
16410 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 nly available if
16420 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f SQLite is.** co
16430 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f mpiled for Windo
16440 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c ws with the [SQL
16450 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 ITE_WIN32_MALLOC
16460 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 ] pre-processor
16470 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 macro.** defined
16480 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 . ^SQLITE_CONFIG
16490 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 _WIN32_HEAPSIZE
164a0 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 takes a 32-bit u
164b0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 nsigned integer
164c0 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 value.** that sp
164d0 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 ecifies the maxi
164e0 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 mum size of the
164f0 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a created heap..**
16500 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
16510 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a FIG_PCACHE_HDRSZ
16520 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
16530 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 _CONFIG_PCACHE_H
16540 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 DRSZ.** <dd>^The
16550 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
16560 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 CACHE_HDRSZ opti
16570 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
16580 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 e parameter whic
16590 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 h.** is a pointe
165a0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 r to an integer
165b0 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 and writes into
165c0 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 that integer the
165d0 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 number of extra
165e0 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 .** bytes per pa
165f0 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 ge required for
16600 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 each page in [SQ
16610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
16620 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 CACHE]..** The a
16630 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 mount of extra s
16640 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61 pace required ca
16650 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 n change dependi
16660 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c ng on the compil
16670 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c er,.** target pl
16680 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 atform, and SQLi
16690 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a te version..**.*
166a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
166b0 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 G_PMASZ]].** <dt
166c0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 >SQLITE_CONFIG_P
166d0 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 MASZ.** <dd>^The
166e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
166f0 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 MASZ option take
16700 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d s a single param
16710 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 eter which.** is
16720 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 an unsigned int
16730 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 eger and sets th
16740 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 e "Minimum PMA S
16750 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c ize" for the mul
16760 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f tithreaded.** so
16770 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 rter to that int
16780 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 eger. The defau
16790 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 lt minimum PMA S
167a0 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68 ize is set by th
167b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 e.** [SQLITE_SOR
167c0 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 TER_PMASZ] compi
167d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 le-time option.
167e0 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65 New threads are
167f0 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 launched.** to
16800 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f help with sort o
16810 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d perations when m
16820 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 ultithreaded sor
16830 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c ting.** is enabl
16840 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 ed (using the [P
16850 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 RAGMA threads] c
16860 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 ommand) and the
16870 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e amount of conten
16880 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 t.** to be sorte
16890 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61 d exceeds the pa
168a0 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 ge size times th
168b0 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 e minimum of the
168c0 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 .** [PRAGMA cach
168d0 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 e_size] setting
168e0 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a and this value..
168f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
16900 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 ONFIG_STMTJRNL_S
16910 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 PILL]].** <dt>SQ
16920 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 LITE_CONFIG_STMT
16930 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 JRNL_SPILL.** <d
16940 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f d>^The SQLITE_CO
16950 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 NFIG_STMTJRNL_SP
16960 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 ILL option takes
16970 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 a single parame
16980 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 ter which.** bec
16990 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d omes the [statem
169a0 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 ent journal] spi
169b0 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 ll-to-disk thres
169c0 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 hold. .** [Stat
169d0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 ement journals]
169e0 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f are held in memo
169f0 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73 ry until their s
16a00 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a ize (in bytes).*
16a10 2a 20 65 78 63 65 65 64 73 20 74 68 69 73 20 74 * exceeds this t
16a20 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 hreshold, at whi
16a30 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72 ch point they ar
16a40 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 e written to dis
16a50 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 k..** Or if the
16a60 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c threshold is -1,
16a70 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e statement journ
16a80 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20 68 als are always h
16a90 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 eld.** exclusive
16aa0 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a ly in memory..**
16ab0 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 Since many stat
16ac0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e ement journals n
16ad0 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 ever become larg
16ae0 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20 73 e, setting the s
16af0 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c pill.** threshol
16b00 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63 d to a value suc
16b10 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67 h as 64KiB can g
16b20 72 65 61 74 6c 79 20 72 65 64 75 63 65 20 74 68 reatly reduce th
16b30 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 e amount of.** I
16b40 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20 73 /O required to s
16b50 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 upport statement
16b60 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 rollback..** Th
16b70 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 e default value
16b80 66 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e 67 for this setting
16b90 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 is controlled b
16ba0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 y the.** [SQLITE
16bb0 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d _STMTJRNL_SPILL]
16bc0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
16bd0 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a tion..** </dl>.*
16be0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16bf0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
16c00 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 READ 1 /* nil
16c10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16c20 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
16c30 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c READ 2 /* nil
16c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16c50 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
16c60 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 IZED 3 /* ni
16c70 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
16c80 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
16c90 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 C 4 /* s
16ca0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
16cb0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
16cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
16cd0 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a MALLOC 5 /*
16ce0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
16cf0 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 hods* */.#define
16d00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
16d10 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 CRATCH 6
16d20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a /* void*, int sz
16d30 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 , int N */.#defi
16d40 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
16d50 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 _PAGECACHE 7
16d60 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
16d70 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 sz, int N */.#de
16d80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
16d90 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 IG_HEAP
16da0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 8 /* void*, in
16db0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e t nByte, int min
16dc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16dd0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
16de0 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f TUS 9 /* bo
16df0 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 olean */.#define
16e00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
16e10 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 UTEX 10
16e20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 /* sqlite3_mutex
16e30 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
16e40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
16e50 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 IG_GETMUTEX
16e60 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 11 /* sqlite3_m
16e70 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f utex_methods* */
16e80 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 ./* previously S
16e90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 QLITE_CONFIG_CHU
16ea0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 NKALLOC 12 which
16eb0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 is now unused.
16ec0 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */ .#define SQLI
16ed0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 TE_CONFIG_LOOKAS
16ee0 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e IDE 13 /* in
16ef0 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 t int */.#define
16f00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
16f10 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 CACHE 14
16f20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 /* no-op */.#def
16f30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
16f40 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 G_GETPCACHE 1
16f50 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 5 /* no-op */.#
16f60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
16f70 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 NFIG_LOG
16f80 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 16 /* xFunc,
16f90 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 void* */.#define
16fa0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 SQLITE_CONFIG_U
16fb0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 RI 17
16fc0 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e /* int */.#defin
16fd0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16fe0 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 PCACHE2 18
16ff0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 /* sqlite3_pcac
17000 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a he_methods2* */.
17010 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
17020 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 ONFIG_GETPCACHE2
17030 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 19 /* sqlite
17040 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
17050 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 2* */.#define SQ
17060 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 LITE_CONFIG_COVE
17070 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 RING_INDEX_SCAN
17080 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 20 /* int */.#d
17090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
170a0 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 FIG_SQLLOG
170b0 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 21 /* xSqllog,
170c0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e void* */.#defin
170d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
170e0 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 MMAP_SIZE 22
170f0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 /* sqlite3_int6
17100 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 4, sqlite3_int64
17110 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17120 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f TE_CONFIG_WIN32_
17130 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 HEAPSIZE 23
17140 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a /* int nByte *
17150 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17160 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 _CONFIG_PCACHE_H
17170 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 DRSZ 24
17180 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 /* int *psz */.#
17190 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
171a0 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 NFIG_PMASZ
171b0 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 25 /*
171c0 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 unsigned int szP
171d0 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ma */.#define SQ
171e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 LITE_CONFIG_STMT
171f0 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 JRNL_SPILL
17200 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 26 /* int nByte
17210 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
17220 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f REF: Database Co
17230 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 nnection Configu
17240 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a ration Options.*
17250 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
17260 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 ants are the ava
17270 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 ilable integer c
17280 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
17290 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e ions that.** can
172a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 be passed as th
172b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
172c0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 t to the [sqlite
172d0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 3_db_config()] i
172e0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
172f0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f New configuratio
17300 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 n options may be
17310 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
17320 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
17330 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 ite..** Existing
17340 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
17350 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 ptions might be
17360 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 discontinued. A
17370 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
17380 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 hould check the
17390 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d return code from
173a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
173b0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 fig()] to make s
173c0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ure that.** the
173d0 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 call worked. ^T
173e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 he [sqlite3_db_c
173f0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 onfig()] interfa
17400 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 ce will return a
17410 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 .** non-zero [er
17420 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 ror code] if a d
17430 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 iscontinued or u
17440 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 nsupported confi
17450 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a guration option.
17460 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a ** is invoked..*
17470 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 *.** <dl>.** <dt
17480 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 >SQLITE_DBCONFIG
17490 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a _LOOKASIDE</dt>.
174a0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
174b0 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 tion takes three
174c0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 additional argu
174d0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 ments that deter
174e0 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f mine the .** [lo
174f0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 okaside memory a
17500 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 llocator] config
17510 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 uration for the
17520 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
17530 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 tion]..** ^The f
17540 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 irst argument (t
17550 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
17560 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 er to [sqlite3_d
17570 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 b_config()] is a
17580 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 .** pointer to a
17590 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 memory buffer t
175a0 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 o use for lookas
175b0 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e ide memory..** ^
175c0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
175d0 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c nt after the SQL
175e0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
175f0 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d KASIDE verb.** m
17600 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 ay be NULL in wh
17610 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 ich case SQLite
17620 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 will allocate th
17630 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 e.** lookaside b
17640 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 uffer itself usi
17650 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ng [sqlite3_mall
17660 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f oc()]. ^The seco
17670 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 nd argument is t
17680 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 he.** size of ea
17690 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 ch lookaside buf
176a0 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 fer slot. ^The
176b0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
176c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a s the number of.
176d0 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 ** slots. The s
176e0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 ize of the buffe
176f0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 r in the first a
17700 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 rgument must be
17710 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 greater than.**
17720 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 or equal to the
17730 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 product of the s
17740 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 econd and third
17750 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 arguments. The
17760 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 buffer.** must b
17770 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
17780 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 8-byte boundary.
17790 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 ^If the second
177a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
177b0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
177c0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 LOOKASIDE is not
177d0 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 a multiple of 8
177e0 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c , it is internal
177f0 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f ly.** rounded do
17800 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 wn to the next s
17810 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 maller multiple
17820 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f of 8. ^(The loo
17830 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a kaside memory.**
17840 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 configuration f
17850 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f or a database co
17860 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c nnection can onl
17870 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 y be changed whe
17880 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 n that.** connec
17890 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 tion is not curr
178a0 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b ently using look
178b0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 aside memory, or
178c0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a in other words.
178d0 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 ** when the "cur
178e0 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 rent value" retu
178f0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 rned by.** [sqli
17900 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 te3_db_status](D
17910 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ,[SQLITE_CONFIG_
17920 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 LOOKASIDE],...)
17930 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 is zero..** Any
17940 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 attempt to chang
17950 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 e the lookaside
17960 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 memory configura
17970 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 tion when lookas
17980 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 ide.** memory is
17990 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 in use leaves t
179a0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e he configuration
179b0 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 unchanged and r
179c0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 eturns .** [SQLI
179d0 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e TE_BUSY].)^</dd>
179e0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
179f0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
17a00 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c E_FKEY</dt>.** <
17a10 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
17a20 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 is used to enab
17a30 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 le or disable th
17a40 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 e enforcement of
17a50 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 .** [foreign key
17a60 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 constraints].
17a70 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 There should be
17a80 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 two additional a
17a90 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 rguments..** The
17aa0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
17ab0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 is an integer wh
17ac0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 ich is 0 to disa
17ad0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 ble FK enforceme
17ae0 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 nt,.** positive
17af0 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 to enable FK enf
17b00 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 orcement or nega
17b10 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b tive to leave FK
17b20 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 enforcement.**
17b30 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 unchanged. The
17b40 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
17b50 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
17b60 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f an integer into
17b70 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 which.** is wri
17b80 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 tten 0 or 1 to i
17b90 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 ndicate whether
17ba0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 FK enforcement i
17bb0 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 s off or on.** f
17bc0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 ollowing this ca
17bd0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ll. The second
17be0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
17bf0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
17c00 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 in.** which cas
17c10 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 e the FK enforce
17c20 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 ment setting is
17c30 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 not reported bac
17c40 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c k. </dd>.**.** <
17c50 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
17c60 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 IG_ENABLE_TRIGGE
17c70 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e R</dt>.** <dd> ^
17c80 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 This option is u
17c90 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 sed to enable or
17ca0 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 disable [CREATE
17cb0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 TRIGGER | trigg
17cc0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 ers]..** There s
17cd0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 hould be two add
17ce0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
17cf0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 s..** The first
17d00 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 argument is an i
17d10 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 nteger which is
17d20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 0 to disable tri
17d30 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 ggers,.** positi
17d40 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 ve to enable tri
17d50 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 ggers or negativ
17d60 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 e to leave the s
17d70 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 etting unchanged
17d80 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
17d90 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
17da0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
17db0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a eger into which.
17dc0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 ** is written 0
17dd0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 or 1 to indicate
17de0 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 whether trigger
17df0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f s are disabled o
17e00 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c r enabled.** fol
17e10 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c lowing this call
17e20 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . The second pa
17e30 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 rameter may be a
17e40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 NULL pointer, i
17e50 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 n.** which case
17e60 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 the trigger sett
17e70 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 ing is not repor
17e80 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a ted back. </dd>.
17e90 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
17ea0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
17eb0 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c _FTS3_TOKENIZER<
17ec0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
17ed0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 is option is use
17ee0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 d to enable or d
17ef0 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 isable the two-a
17f00 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 rgument.** versi
17f10 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f on of the [fts3_
17f20 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e tokenizer()] fun
17f30 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70 ction which is p
17f40 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 art of the.** [F
17f50 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 TS3] full-text s
17f60 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74 earch engine ext
17f70 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 ension..** There
17f80 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 should be two a
17f90 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 dditional argume
17fa0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 nts..** The firs
17fb0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e t argument is an
17fc0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 integer which i
17fd0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66 s 0 to disable f
17fe0 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 ts3_tokenizer()
17ff0 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 or.** positive t
18000 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f o enable fts3_to
18010 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 kenizer() or neg
18020 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 ative to leave t
18030 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e he setting.** un
18040 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 changed..** The
18050 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
18060 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
18070 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f an integer into
18080 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 which.** is wri
18090 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 tten 0 or 1 to i
180a0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 ndicate whether
180b0 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 fts3_tokenizer i
180c0 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e s disabled or en
180d0 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 abled.** followi
180e0 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 ng this call. T
180f0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
18100 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c ter may be a NUL
18110 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a L pointer, in.**
18120 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 which case the
18130 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e new setting is n
18140 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b ot reported back
18150 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 . </dd>.**.** <d
18160 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
18170 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 G_ENABLE_LOAD_EX
18180 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 TENSION</dt>.**
18190 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
181a0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 n is used to ena
181b0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 ble or disable t
181c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 he [sqlite3_load
181d0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a _extension()].**
181e0 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70 interface indep
181f0 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20 endently of the
18200 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 [load_extension(
18210 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e )] SQL function.
18220 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
18230 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 _enable_load_ext
18240 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e ension()] API en
18250 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 ables or disable
18260 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d s both the.** C-
18270 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 API [sqlite3_loa
18280 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61 d_extension()] a
18290 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nd the SQL funct
182a0 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 ion [load_extens
182b0 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 ion()]..** There
182c0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 should be two a
182d0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 dditional argume
182e0 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65 nts..** When the
182f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
18300 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 to this interfac
18310 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c e is 1, then onl
18320 79 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a y the C-API is.*
18330 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 * enabled and th
18340 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 e SQL function r
18350 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e emains disabled.
18360 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20 61 If the first a
18370 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 rgument to.** th
18380 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 is interface is
18390 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65 0, then both the
183a0 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53 C-API and the S
183b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 QL function are
183c0 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 disabled..** If
183d0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
183e0 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e nt is -1, then n
183f0 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61 o changes are ma
18400 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65 de to state of e
18410 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41 ither the.** C-A
18420 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75 PI or the SQL fu
18430 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 nction..** The s
18440 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
18450 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
18460 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 an integer into
18470 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 which.** is writ
18480 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e ten 0 or 1 to in
18490 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 5b dicate whether [
184a0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 sqlite3_load_ext
184b0 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 ension()] interf
184c0 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c ace.** is disabl
184d0 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f ed or enabled fo
184e0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c llowing this cal
184f0 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 l. The second p
18500 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20 arameter may.**
18510 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 be a NULL pointe
18520 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 r, in which case
18530 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 the new setting
18540 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 is not reported
18550 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a back..** </dd>.
18560 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
18570 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 _DBCONFIG_MAINDB
18580 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NAME</dt>.** <dd
18590 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 > ^This option i
185a0 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 s used to change
185b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
185c0 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73 65 "main" database
185d0 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54 68 .** schema. ^Th
185e0 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20 e sole argument
185f0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
18600 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38 20 a constant UTF8
18610 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20 string.** which
18620 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 will become the
18630 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 new schema name
18640 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61 69 in place of "mai
18650 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 n". ^SQLite.**
18660 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20 does not make a
18670 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77 20 copy of the new
18680 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65 main schema name
18690 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65 20 string, so the
186a0 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d application.** m
186b0 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 ust ensure that
186c0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61 73 the argument pas
186d0 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44 42 sed into this DB
186e0 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69 73 CONFIG option is
186f0 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e unchanged.** un
18700 74 69 6c 20 61 66 74 65 72 20 74 68 65 20 64 61 til after the da
18710 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
18720 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 n closes..** </d
18730 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
18740 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f ITE_DBCONFIG_NO_
18750 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 CKPT_ON_CLOSE</d
18760 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c t>.** <dd> Usual
18770 6c 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62 ly, when a datab
18780 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20 ase in wal mode
18790 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74 is closed or det
187a0 61 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a ached from a .**
187b0 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 database handle
187c0 2c 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20 , SQLite checks
187d0 69 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61 if this will mea
187e0 6e 20 74 68 61 74 20 74 68 65 72 65 20 61 72 65 n that there are
187f0 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e now no .** conn
18800 65 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74 ections at all t
18810 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 o the database.
18820 49 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72 If so, it perfor
18830 6d 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20 ms a checkpoint
18840 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65 .** operation be
18850 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65 fore closing the
18860 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69 connection. Thi
18870 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 s option may be
18880 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 used to.** overr
18890 69 64 65 20 74 68 69 73 20 62 65 68 61 76 69 6f ide this behavio
188a0 75 72 2e 20 54 68 65 20 66 69 72 73 74 20 70 61 ur. The first pa
188b0 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 rameter passed t
188c0 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e o this operation
188d0 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 .** is an intege
188e0 72 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20 r - non-zero to
188f0 64 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69 disable checkpoi
18900 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 nts-on-close, or
18910 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65 zero (the.** de
18920 66 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65 fault) to enable
18930 20 74 68 65 6d 2e 20 54 68 65 20 73 65 63 6f 6e them. The secon
18940 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 d parameter is a
18950 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
18960 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 nteger.** into w
18970 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 hich is written
18980 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 0 or 1 to indica
18990 74 65 20 77 68 65 74 68 65 72 20 63 68 65 63 6b te whether check
189a0 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a points-on-close.
189b0 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69 73 ** have been dis
189c0 61 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65 abled - 0 if the
189d0 79 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c y are not disabl
189e0 65 64 2c 20 31 20 69 66 20 74 68 65 79 20 61 72 ed, 1 if they ar
189f0 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a e..** </dd>.**.*
18a00 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 * <dt>SQLITE_DBC
18a10 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 ONFIG_ENABLE_QPS
18a20 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 G</dt>.** <dd>^(
18a30 54 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e The SQLITE_DBCON
18a40 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 FIG_ENABLE_QPSG
18a50 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73 option activates
18a60 20 6f 72 20 64 65 61 63 74 69 76 61 74 65 73 0a or deactivates.
18a70 2a 2a 20 74 68 65 20 5b 71 75 65 72 79 20 70 6c ** the [query pl
18a80 61 6e 6e 65 72 20 73 74 61 62 69 6c 69 74 79 20 anner stability
18a90 67 75 61 72 61 6e 74 65 65 5d 20 28 51 50 53 47 guarantee] (QPSG
18aa0 29 2e 20 20 57 68 65 6e 20 74 68 65 20 51 50 53 ). When the QPS
18ab0 47 20 69 73 20 61 63 74 69 76 65 2c 0a 2a 2a 20 G is active,.**
18ac0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 71 75 65 a single SQL que
18ad0 72 79 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c ry statement wil
18ae0 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 l always use the
18af0 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 same algorithm
18b00 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 regardless.** of
18b10 20 76 61 6c 75 65 73 20 6f 66 20 5b 62 6f 75 6e values of [boun
18b20 64 20 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e d parameters].)^
18b30 20 54 68 65 20 51 50 53 47 20 64 69 73 61 62 6c The QPSG disabl
18b40 65 73 20 73 6f 6d 65 20 71 75 65 72 79 20 6f 70 es some query op
18b50 74 69 6d 69 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74 timizations.** t
18b60 68 61 74 20 6c 6f 6f 6b 20 61 74 20 74 68 65 20 hat look at the
18b70 76 61 6c 75 65 73 20 6f 66 20 62 6f 75 6e 64 20 values of bound
18b80 70 61 72 61 6d 65 74 65 72 73 2c 20 77 68 69 63 parameters, whic
18b90 68 20 63 61 6e 20 6d 61 6b 65 20 73 6f 6d 65 20 h can make some
18ba0 71 75 65 72 69 65 73 0a 2a 2a 20 73 6c 6f 77 65 queries.** slowe
18bb0 72 2e 20 20 42 75 74 20 74 68 65 20 51 50 53 47 r. But the QPSG
18bc0 20 68 61 73 20 74 68 65 20 61 64 76 61 6e 74 61 has the advanta
18bd0 67 65 20 6f 66 20 6d 6f 72 65 20 70 72 65 64 69 ge of more predi
18be0 63 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e ctable behavior.
18bf0 20 20 57 69 74 68 0a 2a 2a 20 74 68 65 20 51 50 With.** the QP
18c00 53 47 20 61 63 74 69 76 65 2c 20 53 51 4c 69 74 SG active, SQLit
18c10 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75 73 e will always us
18c20 65 20 74 68 65 20 73 61 6d 65 20 71 75 65 72 79 e the same query
18c30 20 70 6c 61 6e 20 69 6e 20 74 68 65 20 66 69 65 plan in the fie
18c40 6c 64 20 61 73 0a 2a 2a 20 77 61 73 20 75 73 65 ld as.** was use
18c50 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 d during testing
18c60 20 69 6e 20 74 68 65 20 6c 61 62 2e 0a 2a 2a 20 in the lab..**
18c70 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c </dd>.**.** </dl
18c80 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
18c90 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 ITE_DBCONFIG_MAI
18ca0 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 NDBNAME
18cb0 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 1000 /* const
18cc0 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e char* */.#defin
18cd0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
18ce0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 G_LOOKASIDE
18cf0 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 1001 /*
18d00 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f void* int int */
18d10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18d20 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
18d30 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31 FKEY 1
18d40 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 002 /* int int*
18d50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18d60 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
18d70 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 E_TRIGGER
18d80 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 1003 /* int int
18d90 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
18da0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
18db0 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a BLE_FTS3_TOKENIZ
18dc0 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 ER 1004 /* int i
18dd0 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nt* */.#define S
18de0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
18df0 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e NABLE_LOAD_EXTEN
18e00 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 SION 1005 /* int
18e10 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 int* */.#define
18e20 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
18e30 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 _NO_CKPT_ON_CLOS
18e40 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69 E 1006 /* i
18e50 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 nt int* */.#defi
18e60 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
18e70 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 20 IG_ENABLE_QPSG
18e80 20 20 20 20 20 20 20 20 20 31 30 30 37 20 2f 2a 1007 /*
18e90 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f int int* */.../
18ea0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
18eb0 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 nable Or Disable
18ec0 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 Extended Result
18ed0 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 Codes.** METHOD
18ee0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
18ef0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 ^The sqlite3_ext
18f00 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
18f10 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 es() routine ena
18f20 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 bles or disables
18f30 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 the.** [extende
18f40 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 d result codes]
18f50 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 feature of SQLit
18f60 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 e. ^The extended
18f70 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 result.** codes
18f80 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 are disabled by
18f90 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 default for his
18fa0 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 torical compatib
18fb0 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ility..*/.int sq
18fc0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 lite3_extended_r
18fd0 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 esult_codes(sqli
18fe0 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 te3*, int onoff)
18ff0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
19000 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 F: Last Insert R
19010 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 owid.** METHOD:
19020 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 sqlite3.**.** ^E
19030 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 ach entry in mos
19040 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 t SQLite tables
19050 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 (except for [WIT
19060 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c HOUT ROWID] tabl
19070 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 es).** has a uni
19080 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 que 64-bit signe
19090 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 d.** integer key
190a0 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 called the [ROW
190b0 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e ID | "rowid"]. ^
190c0 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 The rowid is alw
190d0 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a ays available.**
190e0 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 as an undeclare
190f0 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 d column named R
19100 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 OWID, OID, or _R
19110 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 OWID_ as long as
19120 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 those.** names
19130 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 are not also use
19140 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 d by explicitly
19150 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 declared columns
19160 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 . ^If.** the tab
19170 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 le has a column
19180 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 of type [INTEGER
19190 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 PRIMARY KEY] th
191a0 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a en that column.*
191b0 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 * is another ali
191c0 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 as for the rowid
191d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
191e0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
191f0 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 _rowid(D) interf
19200 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75 ace usually retu
19210 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 rns the [rowid]
19220 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 of.** the most r
19230 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c ecent successful
19240 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 [INSERT] into a
19250 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 rowid table or
19260 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a [virtual table].
19270 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 ** on database c
19280 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e onnection D. ^In
19290 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 serts into [WITH
192a0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 OUT ROWID] table
192b0 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 s are not.** rec
192c0 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 orded. ^If no su
192d0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
192e0 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 ]s into rowid ta
192f0 62 6c 65 73 20 68 61 76 65 20 65 76 65 72 20 6f bles have ever o
19300 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 ccurred .** on t
19310 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
19320 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 ection D, then s
19330 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
19340 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 rt_rowid(D) retu
19350 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a rns .** zero..**
19360 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62 .** As well as b
19370 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74 eing set automat
19380 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 ically as rows a
19390 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f re inserted into
193a0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 database.** tab
193b0 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 les, the value r
193c0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 eturned by this
193d0 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 function may be
193e0 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62 set explicitly b
193f0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 y.** [sqlite3_se
19400 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f t_last_insert_ro
19410 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d wid()].**.** Som
19420 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 e virtual table
19430 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
19440 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20 may INSERT rows
19450 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 into rowid table
19460 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 s as.** part of
19470 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61 committing a tra
19480 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 nsaction (e.g. t
19490 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61 63 63 o flush data acc
194a0 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f umulated in memo
194b0 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 ry.** to disk).
194c0 49 6e 20 74 68 69 73 20 63 61 73 65 20 73 75 62 In this case sub
194d0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
194e0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 this function r
194f0 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a eturn the rowid.
19500 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
19510 74 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61 th these interna
19520 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69 l INSERT operati
19530 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73 ons, which leads
19540 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 to .** unintuit
19550 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72 ive results. Vir
19560 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 tual table imple
19570 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20 mentations that
19580 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69 do write to rowi
19590 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 d.** tables in t
195a0 68 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69 his way can avoi
195b0 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 d this problem b
195c0 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20 y restoring the
195d0 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 original .** row
195e0 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b id value using [
195f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 sqlite3_set_last
19600 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d _insert_rowid()]
19610 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e before returnin
19620 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f g .** control to
19630 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a the user..**.**
19640 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 ^(If an [INSERT
19650 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 ] occurs within
19660 61 20 74 72 69 67 67 65 72 20 74 68 65 6e 20 74 a trigger then t
19670 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c his routine will
19680 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 .** return the
19690 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 [rowid] of the i
196a0 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c nserted row as l
196b0 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 ong as the trigg
196c0 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e er is .** runnin
196d0 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67 g. Once the trig
196e0 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 ger program ends
196f0 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 , the value retu
19700 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 rned .** by this
19710 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 routine reverts
19720 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 to what it was
19730 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 before the trigg
19740 65 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a er was fired.)^.
19750 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 **.** ^An [INSER
19760 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 T] that fails du
19770 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e e to a constrain
19780 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e t violation is n
19790 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 ot a.** successf
197a0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 ul [INSERT] and
197b0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 does not change
197c0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
197d0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f ed by this.** ro
197e0 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e utine. ^Thus IN
197f0 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e SERT OR FAIL, IN
19800 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 SERT OR IGNORE,
19810 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 INSERT OR ROLLBA
19820 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 CK,.** and INSER
19830 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 T OR ABORT make
19840 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 no changes to th
19850 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
19860 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e f this.** routin
19870 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 e when their ins
19880 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e ertion fails. ^
19890 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 (When INSERT OR
198a0 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 REPLACE.** encou
198b0 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 nters a constrai
198c0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 nt violation, it
198d0 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 does not fail.
198e0 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 The.** INSERT c
198f0 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 ontinues to comp
19900 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c letion after del
19910 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 eting rows that
19920 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f caused.** the co
19930 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d nstraint problem
19940 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 so INSERT OR RE
19950 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 PLACE will alway
19960 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 s change.** the
19970 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
19980 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 this interface.)
19990 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 ^.**.** ^For the
199a0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 purposes of thi
199b0 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 s routine, an [I
199c0 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 NSERT] is consid
199d0 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 ered to.** be su
199e0 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 ccessful even if
199f0 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e it is subsequen
19a00 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e tly rolled back.
19a10 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
19a20 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 tion is accessib
19a30 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d le to SQL statem
19a40 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 ents via the.**
19a50 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 [last_insert_row
19a60 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f id() SQL functio
19a70 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 n]..**.** If a s
19a80 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 eparate thread p
19a90 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 erforms a new [I
19aa0 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 NSERT] on the sa
19ab0 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 me.** database c
19ac0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 onnection while
19ad0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 the [sqlite3_las
19ae0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 t_insert_rowid()
19af0 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 ].** function is
19b00 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 running and thu
19b10 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 s changes the la
19b20 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 st insert [rowid
19b30 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 ],.** then the v
19b40 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
19b50 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 [sqlite3_last_i
19b60 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 nsert_rowid()] i
19b70 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 s.** unpredictab
19b80 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 le and might not
19b90 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 equal either th
19ba0 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 e old or the new
19bb0 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 .** last insert
19bc0 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 [rowid]..*/.sqli
19bd0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
19be0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
19bf0 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a wid(sqlite3*);..
19c00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
19c10 53 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73 Set the Last Ins
19c20 65 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e ert Rowid value.
19c30 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
19c40 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 te3.**.** The sq
19c50 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 lite3_set_last_i
19c60 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 nsert_rowid(D, R
19c70 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 ) method allows
19c80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
19c90 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61 to.** set the va
19ca0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
19cb0 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f calling sqlite3_
19cc0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
19cd0 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 d(D) to R .** wi
19ce0 74 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20 thout inserting
19cf0 61 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 a row into the d
19d00 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 atabase..*/.void
19d10 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 sqlite3_set_las
19d20 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 t_insert_rowid(s
19d30 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f qlite3*,sqlite3_
19d40 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int64);../*.** C
19d50 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 API3REF: Count T
19d60 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 he Number Of Row
19d70 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 s Modified.** ME
19d80 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
19d90 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
19da0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e on returns the n
19db0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f umber of rows mo
19dc0 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 dified, inserted
19dd0 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 or.** deleted b
19de0 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e y the most recen
19df0 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e tly completed IN
19e00 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 SERT, UPDATE or
19e10 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d DELETE.** statem
19e20 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 ent on the datab
19e30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 ase connection s
19e40 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
19e50 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a only parameter..
19e60 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e ** ^Executing an
19e70 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 y other type of
19e80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f SQL statement do
19e90 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 es not modify th
19ea0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 e value.** retur
19eb0 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 ned by this func
19ec0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c tion..**.** ^Onl
19ed0 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 y changes made d
19ee0 69 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 irectly by the I
19ef0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 NSERT, UPDATE or
19f00 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e DELETE statemen
19f10 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 t are.** conside
19f20 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 red - auxiliary
19f30 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 changes caused b
19f40 79 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 y [CREATE TRIGGE
19f50 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a R | triggers], .
19f60 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 ** [foreign key
19f70 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 actions] or [REP
19f80 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 LACE] constraint
19f90 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 resolution are
19fa0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 not counted..**
19fb0 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 .** Changes to a
19fc0 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 view that are i
19fd0 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a ntercepted by .*
19fe0 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 * [INSTEAD OF tr
19ff0 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 igger | INSTEAD
1a000 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 OF triggers] are
1a010 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 not counted. ^T
1a020 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 he value .** ret
1a030 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
1a040 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 _changes() immed
1a050 69 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 iately after an
1a060 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f INSERT, UPDATE o
1a070 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 r .** DELETE sta
1a080 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 tement run on a
1a090 76 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a view is always z
1a0a0 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 ero. Only change
1a0b0 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a s made to real .
1a0c0 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f ** tables are co
1a0d0 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 unted..**.** Thi
1a0e0 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d ngs are more com
1a0f0 70 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 plicated if the
1a100 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
1a110 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a ) function is.**
1a120 20 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 executed while
1a130 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 a trigger progra
1a140 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 m is running. Th
1a150 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 is may happen if
1a160 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 the.** program
1a170 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 uses the [change
1a180 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e s() SQL function
1a190 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 ], or if some ot
1a1a0 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 her callback.**
1a1b0 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 function invokes
1a1c0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
1a1d0 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 () directly. Ess
1a1e0 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a entially:.** .**
1a1f0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 <ul>.** <li>
1a200 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e ^(Before enterin
1a210 67 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 g a trigger prog
1a220 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 ram the value re
1a230 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 turned by.**
1a240 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e sqlite3_chan
1a250 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 ges() function i
1a260 73 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 s saved. After t
1a270 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 he trigger progr
1a280 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 am .** ha
1a290 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 s finished, the
1a2a0 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 original value i
1a2b0 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a s restored.)^.**
1a2c0 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 .** <li> ^(Wi
1a2d0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 thin a trigger p
1a2e0 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 rogram each INSE
1a2f0 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 RT, UPDATE and D
1a300 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 ELETE .**
1a310 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 statement sets
1a320 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
1a330 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 ed by sqlite3_ch
1a340 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 anges() .**
1a350 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 upon completi
1a360 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 on as normal. Of
1a370 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 course, this va
1a380 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 lue will not inc
1a390 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 lude .**
1a3a0 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 any changes perf
1a3b0 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 ormed by sub-tri
1a3c0 67 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 ggers, as the sq
1a3d0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 lite3_changes()
1a3e0 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 .** value
1a3f0 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 will be saved a
1a400 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 nd restored afte
1a410 72 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 r each sub-trigg
1a420 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a er has run.)^.**
1a430 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 </ul>.** .** ^T
1a440 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 his means that i
1a450 66 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 f the changes()
1a460 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 SQL function (or
1a470 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 similar) is use
1a480 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 d.** by the firs
1a490 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 t INSERT, UPDATE
1a4a0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 or DELETE state
1a4b0 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 ment within a tr
1a4c0 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 igger, it .** re
1a4d0 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 turns the value
1a4e0 61 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 as set when the
1a4f0 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e calling statemen
1a500 74 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e t began executin
1a510 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 g..** ^If it is
1a520 75 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f used by the seco
1a530 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 nd or subsequent
1a540 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 such statement
1a550 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 within a trigger
1a560 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 .** program, th
1a570 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
1a580 20 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 reflects the nu
1a590 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 mber of rows mod
1a5a0 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a ified by the .**
1a5b0 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 previous INSERT
1a5c0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 , UPDATE or DELE
1a5d0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 TE statement wit
1a5e0 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 hin the same tri
1a5f0 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 gger..**.** See
1a600 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 also the [sqlite
1a610 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
1a620 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 )] interface, th
1a630 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e e.** [count_chan
1a640 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 ges pragma], and
1a650 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 the [changes()
1a660 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a SQL function]..*
1a670 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 *.** If a separa
1a680 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 te thread makes
1a690 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 changes on the s
1a6a0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
1a6b0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 nection.** while
1a6c0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 [sqlite3_change
1a6d0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 s()] is running
1a6e0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 then the value r
1a6f0 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e eturned.** is un
1a700 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 predictable and
1a710 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a not meaningful..
1a720 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
1a730 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 hanges(sqlite3*)
1a740 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1a750 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 F: Total Number
1a760 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 Of Rows Modified
1a770 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
1a780 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 te3.**.** ^This
1a790 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
1a7a0 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 the total numbe
1a7b0 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 r of rows insert
1a7c0 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a ed, modified or.
1a7d0 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c ** deleted by al
1a7e0 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 l [INSERT], [UPD
1a7f0 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d ATE] or [DELETE]
1a800 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 statements comp
1a810 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 leted.** since t
1a820 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1a830 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 ection was opene
1a840 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f d, including tho
1a850 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a se executed as.*
1a860 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 * part of trigge
1a870 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 r programs. ^Exe
1a880 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 cuting any other
1a890 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 type of SQL sta
1a8a0 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e tement.** does n
1a8b0 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 ot affect the va
1a8c0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
1a8d0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
1a8e0 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 anges()..** .**
1a8f0 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 ^Changes made as
1a900 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 part of [foreig
1a910 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 n key actions] a
1a920 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 re included in t
1a930 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 he.** count, but
1a940 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 those made as p
1a950 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 art of REPLACE c
1a960 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 onstraint resolu
1a970 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e tion are.** not.
1a980 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 ^Changes to a v
1a990 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 iew that are int
1a9a0 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 ercepted by INST
1a9b0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 EAD OF triggers
1a9c0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e .** are not coun
1a9d0 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 ted..** .** See
1a9e0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 also the [sqlite
1a9f0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 3_changes()] int
1aa00 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b erface, the.** [
1aa10 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 count_changes pr
1aa20 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b agma], and the [
1aa30 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 total_changes()
1aa40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a SQL function]..*
1aa50 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 *.** If a separa
1aa60 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 te thread makes
1aa70 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 changes on the s
1aa80 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
1aa90 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 nection.** while
1aaa0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f [sqlite3_total_
1aab0 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 changes()] is ru
1aac0 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 nning then the v
1aad0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 alue.** returned
1aae0 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c is unpredictabl
1aaf0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e e and not meanin
1ab00 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c gful..*/.int sql
1ab10 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
1ab20 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
1ab30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
1ab40 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d nterrupt A Long-
1ab50 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a Running Query.**
1ab60 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
1ab70 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e .**.** ^This fun
1ab80 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 ction causes any
1ab90 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 pending databas
1aba0 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 e operation to a
1abb0 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 bort and.** retu
1abc0 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 rn at its earlie
1abd0 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 st opportunity.
1abe0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 This routine is
1abf0 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c typically.** cal
1ac00 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 led in response
1ac10 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e to a user action
1ac20 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e such as pressin
1ac30 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 g "Cancel".** or
1ac40 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 Ctrl-C where th
1ac50 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c e user wants a l
1ac60 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 ong query operat
1ac70 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 ion to halt.** i
1ac80 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a mmediately..**.*
1ac90 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f * ^It is safe to
1aca0 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 call this routi
1acb0 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 ne from a thread
1acc0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 different from
1acd0 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 the.** thread th
1ace0 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 at is currently
1acf0 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 running the data
1ad00 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 base operation.
1ad10 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f But it.** is no
1ad20 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 t safe to call t
1ad30 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
1ad40 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
1ad50 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a nection] that.**
1ad60 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 is closed or mi
1ad70 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 ght close before
1ad80 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
1ad90 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a pt() returns..**
1ada0 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f .** ^If an SQL o
1adb0 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 peration is very
1adc0 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 nearly finished
1add0 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 at the time whe
1ade0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 n.** sqlite3_int
1adf0 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c errupt() is call
1ae00 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 ed, then it migh
1ae10 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 t not have an op
1ae20 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 portunity.** to
1ae30 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 be interrupted a
1ae40 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 nd might continu
1ae50 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e e to completion.
1ae60 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f .**.** ^An SQL o
1ae70 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 peration that is
1ae80 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c interrupted wil
1ae90 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
1aea0 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 _INTERRUPT]..**
1aeb0 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 ^If the interrup
1aec0 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f ted SQL operatio
1aed0 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 n is an INSERT,
1aee0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 UPDATE, or DELET
1aef0 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 E.** that is ins
1af00 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 ide an explicit
1af10 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 transaction, the
1af20 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 n the entire tra
1af30 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c nsaction.** will
1af40 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 be rolled back
1af50 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a automatically..*
1af60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1af70 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 3_interrupt(D) c
1af80 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 all is in effect
1af90 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 until all curre
1afa0 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 ntly running.**
1afb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f SQL statements o
1afc0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
1afd0 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 ection] D comple
1afe0 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 te. ^Any new SQ
1aff0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
1b000 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 that are started
1b010 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 after the sqlit
1b020 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 e3_interrupt() c
1b030 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 all and before t
1b040 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 he .** running s
1b050 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 tatements reache
1b060 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 s zero are inter
1b070 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 rupted as if the
1b080 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 y had been.** ru
1b090 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 nning prior to t
1b0a0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
1b0b0 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e rupt() call. ^N
1b0c0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ew SQL statement
1b0d0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 s.** that are st
1b0e0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 arted after the
1b0f0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e running statemen
1b100 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 t count reaches
1b110 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 zero are.** not
1b120 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 effected by the
1b130 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
1b140 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 t()..** ^A call
1b150 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 to sqlite3_inter
1b160 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 rupt(D) that occ
1b170 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 urs when there a
1b180 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a re no running.**
1b190 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
1b1a0 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 is a no-op and h
1b1b0 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 as no effect on
1b1c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
1b1d0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 * that are start
1b1e0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c ed after the sql
1b1f0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
1b200 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a call returns..*
1b210 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 /.void sqlite3_i
1b220 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 nterrupt(sqlite3
1b230 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1b240 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 REF: Determine I
1b250 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 f An SQL Stateme
1b260 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a nt Is Complete.*
1b270 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
1b280 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 nes are useful d
1b290 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 uring command-li
1b2a0 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 ne input to dete
1b2b0 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 rmine if the.**
1b2c0 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 currently entere
1b2d0 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 d text seems to
1b2e0 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 form a complete
1b2f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 SQL statement or
1b300 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 .** if additiona
1b310 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 l input is neede
1b320 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 d before sending
1b330 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a the text into.*
1b340 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 * SQLite for par
1b350 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f sing. ^These ro
1b360 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 utines return 1
1b370 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 if the input str
1b380 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 ing.** appears t
1b390 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 o be a complete
1b3a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 SQL statement.
1b3b0 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 ^A statement is
1b3c0 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 judged to be.**
1b3d0 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 complete if it e
1b3e0 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 nds with a semic
1b3f0 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 olon token and i
1b400 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f s not a prefix o
1b410 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d f a.** well-form
1b420 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 ed CREATE TRIGGE
1b430 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 R statement. ^S
1b440 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 emicolons that a
1b450 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 re embedded with
1b460 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 in.** string lit
1b470 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 erals or quoted
1b480 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 identifier names
1b490 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 or comments are
1b4a0 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 not.** independ
1b4b0 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 ent tokens (they
1b4c0 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 are part of the
1b4d0 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 token in which
1b4e0 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 they are.** embe
1b4f0 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 dded) and thus d
1b500 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 o not count as a
1b510 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 statement termi
1b520 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 nator. ^Whitesp
1b530 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 ace.** and comme
1b540 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 nts that follow
1b550 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f the final semico
1b560 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e lon are ignored.
1b570 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
1b580 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 utines return 0
1b590 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 if the statement
1b5a0 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 is incomplete.
1b5b0 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 ^If a.** memory
1b5c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c allocation fail
1b5d0 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e s, then SQLITE_N
1b5e0 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 OMEM is returned
1b5f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 ..**.** ^These r
1b600 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 outines do not p
1b610 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 arse the SQL sta
1b620 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 tements thus.**
1b630 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 will not detect
1b640 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e syntactically in
1b650 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a correct SQL..**.
1b660 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 ** ^(If SQLite h
1b670 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 as not been init
1b680 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 ialized using [s
1b690 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
1b6a0 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 e()] prior .** t
1b6b0 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 o invoking sqlit
1b6c0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 e3_complete16()
1b6d0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 then sqlite3_ini
1b6e0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 tialize() is inv
1b6f0 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 oked.** automati
1b700 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 cally by sqlite3
1b710 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 _complete16().
1b720 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 If that initiali
1b730 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a zation fails,.**
1b740 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e then the return
1b750 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
1b760 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 te3_complete16()
1b770 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 will be non-zer
1b780 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 o.** regardless
1b790 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
1b7a0 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 t the input SQL
1b7b0 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a is complete.)^.*
1b7c0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 *.** The input t
1b7d0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c o [sqlite3_compl
1b7e0 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 ete()] must be a
1b7f0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1b800 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 .** UTF-8 string
1b810 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 ..**.** The inpu
1b820 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f t to [sqlite3_co
1b830 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 mplete16()] must
1b840 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 be a zero-termi
1b850 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 nated.** UTF-16
1b860 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 string in native
1b870 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a byte order..*/.
1b880 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 int sqlite3_comp
1b890 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 lete(const char
1b8a0 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 *sql);.int sqlit
1b8b0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f e3_complete16(co
1b8c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a nst void *sql);.
1b8d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1b8e0 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c Register A Call
1b8f0 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 back To Handle S
1b900 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 QLITE_BUSY Error
1b910 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
1b920 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c busy-handler cal
1b930 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e lback} {busy han
1b940 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a dler}.** METHOD:
1b950 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
1b960 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 The sqlite3_busy
1b970 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 _handler(D,X,P)
1b980 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 routine sets a c
1b990 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
1b9a0 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 X.** that might
1b9b0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
1b9c0 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e argument P when
1b9d0 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d ever.** an attem
1b9e0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 pt is made to ac
1b9f0 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20 cess a database
1ba00 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 table associated
1ba10 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 with.** [databa
1ba20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
1ba30 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 when another th
1ba40 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 read.** or proce
1ba50 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 ss has the table
1ba60 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 locked..** The
1ba70 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
1ba80 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 dler() interface
1ba90 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c is used to impl
1baa0 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 ement.** [sqlite
1bab0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 3_busy_timeout()
1bac0 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 ] and [PRAGMA bu
1bad0 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a sy_timeout]..**.
1bae0 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 ** ^If the busy
1baf0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
1bb00 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 , then [SQLITE_B
1bb10 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 USY].** is retur
1bb20 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 ned immediately
1bb30 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e upon encounterin
1bb40 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 g the lock. ^If
1bb50 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 the busy callba
1bb60 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c ck.** is not NUL
1bb70 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c L, then the call
1bb80 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e back might be in
1bb90 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 voked with two a
1bba0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 rguments..**.**
1bbb0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
1bbc0 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 ent to the busy
1bbd0 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 handler is a cop
1bbe0 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 y of the void* p
1bbf0 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 ointer which.**
1bc00 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 is the third arg
1bc10 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
1bc20 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e _busy_handler().
1bc30 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 ^The second ar
1bc40 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 gument to.** the
1bc50 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 busy handler ca
1bc60 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 llback is the nu
1bc70 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 mber of times th
1bc80 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 at the busy hand
1bc90 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 ler has.** been
1bca0 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 invoked previous
1bcb0 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 ly for the same
1bcc0 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 locking event.
1bcd0 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 ^If the.** busy
1bce0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
1bcf0 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 0, then no addi
1bd00 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 tional attempts
1bd10 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 are made to.** a
1bd20 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 ccess the databa
1bd30 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 se and [SQLITE_B
1bd40 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 USY] is returned
1bd50 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 .** to the appli
1bd60 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 cation..** ^If t
1bd70 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
1bd80 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
1bd90 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d en another attem
1bda0 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f pt.** is made to
1bdb0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 access the data
1bdc0 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 base and the cyc
1bdd0 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a le repeats..**.*
1bde0 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f * The presence o
1bdf0 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 f a busy handler
1be00 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e does not guaran
1be10 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c tee that it will
1be20 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 be invoked.** w
1be30 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 hen there is loc
1be40 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 k contention. ^I
1be50 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 f SQLite determi
1be60 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e nes that invokin
1be70 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 g the busy.** ha
1be80 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 ndler could resu
1be90 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b lt in a deadlock
1bea0 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 , it will go ahe
1beb0 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 ad and return [S
1bec0 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 QLITE_BUSY].** t
1bed0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f o the applicatio
1bee0 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 n instead of inv
1bef0 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 oking the .** bu
1bf00 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 sy handler..** C
1bf10 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 onsider a scenar
1bf20 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f io where one pro
1bf30 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 cess is holding
1bf40 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 a read lock that
1bf50 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 .** it is trying
1bf60 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 to promote to a
1bf70 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 reserved lock a
1bf80 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 nd.** a second p
1bf90 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e rocess is holdin
1bfa0 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 g a reserved loc
1bfb0 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 k that it is try
1bfc0 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 ing.** to promot
1bfd0 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 e to an exclusiv
1bfe0 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 e lock. The fir
1bff0 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f st process canno
1c000 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 t proceed.** bec
1c010 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b ause it is block
1c020 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 ed by the second
1c030 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 and the second
1c040 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a process cannot.*
1c050 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 * proceed becaus
1c060 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 e it is blocked
1c070 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 by the first. I
1c080 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 f both processes
1c090 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 .** invoke the b
1c0a0 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 usy handlers, ne
1c0b0 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 ither will make
1c0c0 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 any progress. T
1c0d0 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c herefore,.** SQL
1c0e0 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ite returns [SQL
1c0f0 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 ITE_BUSY] for th
1c100 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c e first process,
1c110 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 hoping that thi
1c120 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 s.** will induce
1c130 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 the first proce
1c140 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 ss to release it
1c150 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 s read lock and
1c160 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 allow.** the sec
1c170 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 ond process to p
1c180 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 roceed..**.** ^T
1c190 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 he default busy
1c1a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
1c1b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 ..**.** ^(There
1c1c0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 can only be a si
1c1d0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 ngle busy handle
1c1e0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 r defined for ea
1c1f0 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ch.** [database
1c200 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 connection]. Se
1c210 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 tting a new busy
1c220 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 handler clears
1c230 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c any.** previousl
1c240 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e y set handler.)^
1c250 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c ^Note that cal
1c260 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 ling [sqlite3_bu
1c270 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a sy_timeout()].**
1c280 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b or evaluating [
1c290 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 PRAGMA busy_time
1c2a0 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e out=N] will chan
1c2b0 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 ge the.** busy h
1c2c0 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 andler and thus
1c2d0 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f clear any previo
1c2e0 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 usly set busy ha
1c2f0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ndler..**.** The
1c300 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 busy callback s
1c310 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 hould not take a
1c320 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 ny actions which
1c330 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 modify the.** d
1c340 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1c350 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
1c360 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
1c370 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 . In other word
1c380 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 s,.** the busy h
1c390 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 andler is not re
1c3a0 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 entrant. Any su
1c3b0 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 ch actions.** re
1c3c0 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 sult in undefine
1c3d0 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a d behavior..** .
1c3e0 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 ** A busy handle
1c3f0 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 r must not close
1c400 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
1c410 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b nnection.** or [
1c420 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1c430 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 nt] that invoked
1c440 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
1c450 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 r..*/.int sqlite
1c460 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 3_busy_handler(s
1c470 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 qlite3*,int(*)(v
1c480 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 oid*,int),void*)
1c490 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1c4a0 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 F: Set A Busy Ti
1c4b0 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a meout.** METHOD:
1c4c0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
1c4d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 This routine set
1c4e0 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 s a [sqlite3_bus
1c4f0 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 y_handler | busy
1c500 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 handler] that s
1c510 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 leeps.** for a s
1c520 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 pecified amount
1c530 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 of time when a t
1c540 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 able is locked.
1c550 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a ^The handler.**
1c560 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 will sleep mult
1c570 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c iple times until
1c580 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d at least "ms" m
1c590 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 illiseconds of s
1c5a0 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 leeping.** have
1c5b0 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 accumulated. ^A
1c5c0 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d fter at least "m
1c5d0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 s" milliseconds
1c5e0 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 of sleeping,.**
1c5f0 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 the handler retu
1c600 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 rns 0 which caus
1c610 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 es [sqlite3_step
1c620 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a ()] to return.**
1c630 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a [SQLITE_BUSY]..
1c640 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 **.** ^Calling t
1c650 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
1c660 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 an argument les
1c670 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 s than or equal
1c680 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 to zero.** turns
1c690 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 off all busy ha
1c6a0 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ndlers..**.** ^(
1c6b0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 There can only b
1c6c0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 e a single busy
1c6d0 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 handler for a pa
1c6e0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 rticular.** [dat
1c6f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1c700 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d ] at any given m
1c710 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 oment. If anoth
1c720 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a er busy handler.
1c730 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 ** was defined
1c740 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f (using [sqlite3_
1c750 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 busy_handler()])
1c760 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e prior to callin
1c770 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e g.** this routin
1c780 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 e, that other bu
1c790 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c sy handler is cl
1c7a0 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 eared.)^.**.** S
1c7b0 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d ee also: [PRAGM
1c7c0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a A busy_timeout].
1c7d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
1c7e0 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 usy_timeout(sqli
1c7f0 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a te3*, int ms);..
1c800 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1c810 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 Convenience Rout
1c820 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 ines For Running
1c830 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 Queries.** METH
1c840 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
1c850 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 * This is a lega
1c860 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 cy interface tha
1c870 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 t is preserved f
1c880 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d or backwards com
1c890 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 patibility..** U
1c8a0 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 se of this inter
1c8b0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f face is not reco
1c8c0 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 mmended..**.** D
1c8d0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e efinition: A <b>
1c8e0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e result table</b>
1c8f0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 is memory data
1c900 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 structure create
1c910 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c d by the.** [sql
1c920 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
1c930 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 ] interface. A
1c940 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 result table rec
1c950 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 ords the.** comp
1c960 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c lete query resul
1c970 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d ts from one or m
1c980 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a ore queries..**.
1c990 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e ** The table con
1c9a0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 ceptually has a
1c9b0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 number of rows a
1c9c0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 nd columns. But
1c9d0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 .** these number
1c9e0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f s are not part o
1c9f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 f the result tab
1ca00 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 le itself. Thes
1ca10 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 e.** numbers are
1ca20 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 obtained separa
1ca30 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 tely. Let N be
1ca40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f the number of ro
1ca50 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 ws.** and M be t
1ca60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
1ca70 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 umns..**.** A re
1ca80 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e sult table is an
1ca90 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
1caa0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 rs to zero-termi
1cab0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 nated UTF-8 stri
1cac0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 ngs..** There ar
1cad0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e e (N+1)*M elemen
1cae0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e ts in the array.
1caf0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f The first M po
1cb00 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 inters point.**
1cb10 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 to zero-terminat
1cb20 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 ed strings that
1cb30 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d contain the nam
1cb40 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e es of the column
1cb50 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e s..** The remain
1cb60 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 ing entries all
1cb70 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 point to query r
1cb80 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 esults. NULL va
1cb90 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 lues result.** i
1cba0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e n NULL pointers.
1cbb0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 All other valu
1cbc0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 es are in their
1cbd0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 UTF-8 zero-termi
1cbe0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 nated.** string
1cbf0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 representation a
1cc00 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
1cc10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
1cc20 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 xt()]..**.** A r
1cc30 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 esult table migh
1cc40 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 t consist of one
1cc50 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 or more memory
1cc60 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 allocations..**
1cc70 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 It is not safe t
1cc80 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 o pass a result
1cc90 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 table directly t
1cca0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
1ccb0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 )]..** A result
1ccc0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 table should be
1ccd0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e deallocated usin
1cce0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f g [sqlite3_free_
1ccf0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 table()]..**.**
1cd00 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 ^(As an example
1cd10 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 of the result ta
1cd20 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 ble format, supp
1cd30 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 ose a query resu
1cd40 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c lt.** is as foll
1cd50 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ows:.**.** <bloc
1cd60 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
1cd70 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 Name
1cd80 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 | Age.**
1cd90 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d -------------
1cda0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 ----------.**
1cdb0 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 Alice
1cdc0 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 | 43.**
1cdd0 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 Bob | 28
1cde0 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 .** Cindy
1cdf0 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c | 21.** <
1ce00 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1ce10 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 e>.**.** There a
1ce20 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d re two column (M
1ce30 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 ==2) and three r
1ce40 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 ows (N==3). Thu
1ce50 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 s the.** result
1ce60 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 table has 8 entr
1ce70 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 ies. Suppose th
1ce80 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 e result table i
1ce90 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 s stored.** in a
1cea0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a n array names az
1ceb0 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a Result. Then az
1cec0 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 Result holds thi
1ced0 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a s content:.**.**
1cee0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
1cef0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 e>.** azR
1cf00 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 esult[0] = "
1cf10 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 Name";.**
1cf20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d azResult[1]
1cf30 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 = "Age";.**
1cf40 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1cf50 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a ;2] = "Alice";.*
1cf60 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1cf70 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b t[3] = "43";
1cf80 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
1cf90 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f ult[4] = "Bo
1cfa0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a b";.** az
1cfb0 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 Result[5] =
1cfc0 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 "28";.**
1cfd0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 azResult[6]
1cfe0 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 = "Cindy";.**
1cff0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1d000 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 1;7] = "21";.**
1d010 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
1d020 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 te>)^.**.** ^The
1d030 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
1d040 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 le() function ev
1d050 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d aluates one or m
1d060 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e ore.** semicolon
1d070 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 -separated SQL s
1d080 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 tatements in the
1d090 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1d0a0 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 UTF-8.** string
1d0b0 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 of its 2nd para
1d0c0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e meter and return
1d0d0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 s a result table
1d0e0 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 to the.** point
1d0f0 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 er given in its
1d100 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 3rd parameter..*
1d110 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 *.** After the a
1d120 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 pplication has f
1d130 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 inished with the
1d140 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c result from sql
1d150 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
1d160 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 ,.** it must pas
1d170 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 s the result tab
1d180 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 le pointer to sq
1d190 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
1d1a0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a () in order to.*
1d1b0 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 * release the me
1d1c0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 mory that was ma
1d1d0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 lloced. Because
1d1e0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a of the way the.
1d1f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ** [sqlite3_mall
1d200 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 oc()] happens wi
1d210 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 thin sqlite3_get
1d220 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 _table(), the ca
1d230 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f lling.** functio
1d240 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 n must not try t
1d250 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f o call [sqlite3_
1d260 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 free()] directly
1d270 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 . Only.** [sqli
1d280 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
1d290 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c ] is able to rel
1d2a0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 ease the memory
1d2b0 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 properly and saf
1d2c0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ely..**.** The s
1d2d0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
1d2e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
1d2f0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 implemented as a
1d300 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a wrapper around.
1d310 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ** [sqlite3_exec
1d320 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ()]. The sqlite
1d330 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 3_get_table() ro
1d340 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 utine does not h
1d350 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f ave access.** to
1d360 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 any internal da
1d370 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 ta structures of
1d380 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 SQLite. It use
1d390 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 s only the publi
1d3a0 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 c.** interface d
1d3b0 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 efined here. As
1d3c0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 a consequence,
1d3d0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 errors that occu
1d3e0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 r in the.** wrap
1d3f0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 per layer outsid
1d400 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 e of the interna
1d410 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 l [sqlite3_exec(
1d420 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a )] call are not.
1d430 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 ** reflected in
1d440 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
1d450 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 to [sqlite3_err
1d460 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 code()] or.** [s
1d470 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
1d480 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
1d490 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 _get_table(. sq
1d4a0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
1d4b0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 /* An open d
1d4c0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e atabase */. con
1d4d0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
1d4e0 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 /* SQL to be
1d4f0 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 evaluated */. c
1d500 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 har ***pazResult
1d510 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 , /* Results
1d520 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a of the query */.
1d530 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 int *pnRow,
1d540 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 /* Numbe
1d550 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 r of result rows
1d560 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
1d570 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e . int *pnColumn
1d580 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 , /* Numb
1d590 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c er of result col
1d5a0 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 umns written her
1d5b0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a e */. char **pz
1d5c0 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 Errmsg /*
1d5d0 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 Error msg writte
1d5e0 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 n here */.);.voi
1d5f0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 d sqlite3_free_t
1d600 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 able(char **resu
1d610 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 lt);../*.** CAPI
1d620 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 3REF: Formatted
1d630 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 String Printing
1d640 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 Functions.**.**
1d650 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
1d660 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f re work-alikes o
1d670 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 f the "printf()"
1d680 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 family of funct
1d690 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 ions.** from the
1d6a0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 standard C libr
1d6b0 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f ary..** These ro
1d6c0 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e utines understan
1d6d0 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f d most of the co
1d6e0 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 mmon K&R formatt
1d6f0 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 ing options,.**
1d700 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 plus some additi
1d710 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 onal non-standar
1d720 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 d formats, detai
1d730 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f led below..** No
1d740 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 te that some of
1d750 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 the more obscure
1d760 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 formatting opti
1d770 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a ons from recent.
1d780 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 ** C-library sta
1d790 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 ndards are omitt
1d7a0 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 ed from this imp
1d7b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a lementation..**.
1d7c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1d7d0 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 mprintf() and sq
1d7e0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 lite3_vmprintf()
1d7f0 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 routines write
1d800 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 their.** results
1d810 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 into memory obt
1d820 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
1d830 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a te3_malloc()]..*
1d840 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 * The strings re
1d850 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 turned by these
1d860 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f two routines sho
1d870 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 uld be.** releas
1d880 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 ed by [sqlite3_f
1d890 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 ree()]. ^Both r
1d8a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 outines return a
1d8b0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 .** NULL pointer
1d8c0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c if [sqlite3_mal
1d8d0 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 loc()] is unable
1d8e0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f to allocate eno
1d8f0 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f ugh.** memory to
1d900 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 hold the result
1d910 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a ing string..**.*
1d920 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f * ^(The sqlite3_
1d930 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 snprintf() routi
1d940 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f ne is similar to
1d950 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 "snprintf()" fr
1d960 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 om.** the standa
1d970 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 rd C library. T
1d980 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 he result is wri
1d990 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a tten into the.**
1d9a0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 buffer supplied
1d9b0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
1d9c0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 arameter whose s
1d9d0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a ize is given by.
1d9e0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 ** the first par
1d9f0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 ameter. Note tha
1da00 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 t the order of t
1da10 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 he.** first two
1da20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 parameters is re
1da30 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 versed from snpr
1da40 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 intf().)^ This
1da50 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 is an.** histori
1da60 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 cal accident tha
1da70 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 t cannot be fixe
1da80 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 d without breaki
1da90 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 ng.** backwards
1daa0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 compatibility.
1dab0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 ^(Note also that
1dac0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
1dad0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 f().** returns a
1dae0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 pointer to its
1daf0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f buffer instead o
1db00 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a f the number of.
1db10 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 ** characters ac
1db20 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 tually written i
1db30 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 nto the buffer.)
1db40 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 ^ We admit that
1db50 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
1db60 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 f characters wri
1db70 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 tten would be a
1db80 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 more useful retu
1db90 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 rn.** value but
1dba0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 we cannot change
1dbb0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
1dbc0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 ion of sqlite3_s
1dbd0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 nprintf().** now
1dbe0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e without breakin
1dbf0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e g compatibility.
1dc00 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 .**.** ^As long
1dc10 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 as the buffer si
1dc20 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 ze is greater th
1dc30 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 an zero, sqlite3
1dc40 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 _snprintf().** g
1dc50 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 uarantees that t
1dc60 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 he buffer is alw
1dc70 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 ays zero-termina
1dc80 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 ted. ^The first
1dc90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e .** parameter "n
1dca0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 " is the total s
1dcb0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 ize of the buffe
1dcc0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 r, including spa
1dcd0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 ce for.** the ze
1dce0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 ro terminator.
1dcf0 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 So the longest s
1dd00 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 tring that can b
1dd10 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 e completely.**
1dd20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 written will be
1dd30 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a n-1 characters..
1dd40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1dd50 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 e3_vsnprintf() r
1dd60 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 outine is a vara
1dd70 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 rgs version of s
1dd80 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
1dd90 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 )..**.** These r
1dda0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c outines all impl
1ddb0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 ement some addit
1ddc0 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 ional formatting
1ddd0 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 .** options that
1dde0 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 are useful for
1ddf0 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c constructing SQL
1de00 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 statements..**
1de10 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c All of the usual
1de20 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 printf() format
1de30 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 ting options app
1de40 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e ly. In addition
1de50 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 , there.** is ar
1de60 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 e "%q", "%Q", "%
1de70 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 w" and "%z" opti
1de80 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ons..**.** ^(The
1de90 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 %q option works
1dea0 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 like %s in that
1deb0 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 it substitutes
1dec0 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 a nul-terminated
1ded0 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 .** string from
1dee0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 the argument lis
1def0 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 t. But %q also
1df00 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c doubles every '\
1df10 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a '' character..**
1df20 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 %q is designed
1df30 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 for use inside a
1df40 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e string literal.
1df50 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 )^ By doubling
1df60 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 each '\''.** cha
1df70 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 racter it escape
1df80 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 s that character
1df90 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 and allows it t
1dfa0 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e o be inserted in
1dfb0 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 to.** the string
1dfc0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d ..**.** For exam
1dfd0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 ple, assume the
1dfe0 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 string variable
1dff0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 zText contains t
1e000 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a ext as follows:.
1e010 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
1e020 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 e><pre>.** char
1e030 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 *zText = "It's
1e040 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a a happy day!";.*
1e050 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
1e060 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 uote>.**.** One
1e070 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 can use this tex
1e080 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 t in an SQL stat
1e090 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 ement as follows
1e0a0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
1e0b0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 ote><pre>.** ch
1e0c0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 ar *zSQL = sqlit
1e0d0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 e3_mprintf("INSE
1e0e0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 RT INTO table VA
1e0f0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 LUES('%q')", zTe
1e100 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 xt);.** sqlite3
1e110 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 _exec(db, zSQL,
1e120 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 0, 0, 0);.** sq
1e130 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 lite3_free(zSQL)
1e140 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
1e150 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 ckquote>.**.** B
1e160 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f ecause the %q fo
1e170 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 rmat string is u
1e180 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 sed, the '\'' ch
1e190 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 aracter in zText
1e1a0 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 .** is escaped a
1e1b0 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 nd the SQL gener
1e1c0 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f ated is as follo
1e1d0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
1e1e0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1e1f0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
1e200 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 e1 VALUES('It''s
1e210 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a a happy day!').
1e220 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1e230 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 quote>.**.** Thi
1e240 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 s is correct. H
1e250 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e ad we used %s in
1e260 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 stead of %q, the
1e270 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a generated SQL.*
1e280 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f * would have loo
1e290 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a ked like this:.*
1e2a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1e2b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 ><pre>.** INSER
1e2c0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 T INTO table1 VA
1e2d0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 LUES('It's a hap
1e2e0 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f py day!');.** </
1e2f0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1e300 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 >.**.** This sec
1e310 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 ond example is a
1e320 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 n SQL syntax err
1e330 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 or. As a genera
1e340 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c l rule you shoul
1e350 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 d.** always use
1e360 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 %q instead of %s
1e370 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 when inserting
1e380 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 text into a stri
1e390 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a ng literal..**.*
1e3a0 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f * ^(The %Q optio
1e3b0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 n works like %q
1e3c0 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 except it also a
1e3d0 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 dds single quote
1e3e0 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 s around.** the
1e3f0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 outside of the t
1e400 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 otal string. Ad
1e410 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 ditionally, if t
1e420 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 he parameter in
1e430 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 the.** argument
1e440 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 list is a NULL p
1e450 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 ointer, %Q subst
1e460 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 itutes the text
1e470 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a "NULL" (without.
1e480 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 ** single quotes
1e490 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 ).)^ So, for ex
1e4a0 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 ample, one could
1e4b0 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f say:.**.** <blo
1e4c0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
1e4d0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 char *zSQL = s
1e4e0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 qlite3_mprintf("
1e4f0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
1e500 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a e VALUES(%Q)", z
1e510 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 Text);.** sqlit
1e520 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c e3_exec(db, zSQL
1e530 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 , 0, 0, 0);.**
1e540 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 sqlite3_free(zSQ
1e550 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 L);.** </pre></b
1e560 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
1e570 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 The code above
1e580 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f will render a co
1e590 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d rrect SQL statem
1e5a0 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a ent in the zSQL.
1e5b0 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e ** variable even
1e5c0 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 if the zText va
1e5d0 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c riable is a NULL
1e5e0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
1e5f0 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 ^(The "%w" forma
1e600 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 tting option is
1e610 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 like "%q" except
1e620 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73 that it expects
1e630 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 to.** be contai
1e640 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c ned within doubl
1e650 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 e-quotes instead
1e660 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 of single quote
1e670 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 s, and it.** esc
1e680 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d apes the double-
1e690 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 quote character
1e6a0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 instead of the s
1e6b0 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 ingle-quote.** c
1e6c0 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 haracter.)^ The
1e6d0 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 "%w" formatting
1e6e0 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e option is inten
1e6f0 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 ded for safely i
1e700 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c nserting.** tabl
1e710 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d e and column nam
1e720 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 es into a constr
1e730 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d ucted SQL statem
1e740 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ent..**.** ^(The
1e750 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 "%z" formatting
1e760 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 option works li
1e770 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 ke "%s" but with
1e780 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e the.** addition
1e790 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 that after the
1e7a0 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 string has been
1e7b0 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 read and copied
1e7c0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 into.** the resu
1e7d0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 lt, [sqlite3_fre
1e7e0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f e()] is called o
1e7f0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 n the input stri
1e800 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 ng.)^.*/.char *s
1e810 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 qlite3_mprintf(c
1e820 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b onst char*,...);
1e830 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 .char *sqlite3_v
1e840 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 mprintf(const ch
1e850 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 ar*, va_list);.c
1e860 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 har *sqlite3_snp
1e870 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c rintf(int,char*,
1e880 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e const char*, ...
1e890 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 );.char *sqlite3
1e8a0 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 _vsnprintf(int,c
1e8b0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
1e8c0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a , va_list);../*.
1e8d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d ** CAPI3REF: Mem
1e8e0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 ory Allocation S
1e8f0 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 ubsystem.**.** T
1e900 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 he SQLite core u
1e910 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 ses these three
1e920 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c routines for all
1e930 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 of its own.** i
1e940 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 nternal memory a
1e950 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e llocation needs.
1e960 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 "Core" in the p
1e970 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 revious sentence
1e980 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 .** does not inc
1e990 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 lude operating-s
1e9a0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 ystem specific V
1e9b0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
1e9c0 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f n. The.** Windo
1e9d0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 ws VFS uses nati
1e9e0 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 ve malloc() and
1e9f0 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 free() for some
1ea00 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a operations..**.*
1ea10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d * ^The sqlite3_m
1ea20 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 alloc() routine
1ea30 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
1ea40 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 r to a block.**
1ea50 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 of memory at lea
1ea60 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 st N bytes in le
1ea70 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 ngth, where N is
1ea80 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a the parameter..
1ea90 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d ** ^If sqlite3_m
1eaa0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c alloc() is unabl
1eab0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 e to obtain suff
1eac0 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d icient free.** m
1ead0 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e emory, it return
1eae0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
1eaf0 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d . ^If the param
1eb00 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c eter N to.** sql
1eb10 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 ite3_malloc() is
1eb20 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 zero or negativ
1eb30 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d e then sqlite3_m
1eb40 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a alloc() returns.
1eb50 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ** a NULL pointe
1eb60 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 r..**.** ^The sq
1eb70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e lite3_malloc64(N
1eb80 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 ) routine works
1eb90 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c just like.** sql
1eba0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 ite3_malloc(N) e
1ebb0 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 xcept that N is
1ebc0 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 an unsigned 64-b
1ebd0 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 it integer inste
1ebe0 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 ad.** of a signe
1ebf0 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 d 32-bit integer
1ec00 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 ..**.** ^Calling
1ec10 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
1ec20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 with a pointer p
1ec30 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e reviously return
1ec40 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ed.** by sqlite3
1ec50 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c _malloc() or sql
1ec60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 ite3_realloc() r
1ec70 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d eleases that mem
1ec80 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 ory so.** that i
1ec90 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 t might be reuse
1eca0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 d. ^The sqlite3
1ecb0 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 _free() routine
1ecc0 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 is.** a no-op if
1ecd0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 is called with
1ece0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 a NULL pointer.
1ecf0 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 Passing a NULL
1ed00 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 pointer.** to sq
1ed10 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 lite3_free() is
1ed20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 harmless. After
1ed30 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 being freed, me
1ed40 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e mory.** should n
1ed50 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e either be read n
1ed60 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 or written. Eve
1ed70 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f n reading previo
1ed80 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 usly freed.** me
1ed90 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c mory might resul
1eda0 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 t in a segmentat
1edb0 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 ion fault or oth
1edc0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e er severe error.
1edd0 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 .** Memory corru
1ede0 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 ption, a segment
1edf0 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 ation fault, or
1ee00 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 other severe err
1ee10 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 or.** might resu
1ee20 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 lt if sqlite3_fr
1ee30 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 ee() is called w
1ee40 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 ith a non-NULL p
1ee50 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 ointer that.** w
1ee60 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 as not obtained
1ee70 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c from sqlite3_mal
1ee80 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 loc() or sqlite3
1ee90 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a _realloc()..**.*
1eea0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
1eeb0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 ealloc(X,N) inte
1eec0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
1eed0 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 o resize a.** pr
1eee0 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ior memory alloc
1eef0 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 ation X to be at
1ef00 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a least N bytes..
1ef10 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 ** ^If the X par
1ef20 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
1ef30 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 3_realloc(X,N).*
1ef40 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e * is a NULL poin
1ef50 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 ter then its beh
1ef60 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 avior is identic
1ef70 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a al to calling.**
1ef80 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1ef90 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e N)..** ^If the N
1efa0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
1efb0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c lite3_realloc(X,
1efc0 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a N) is zero or.**
1efd0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 negative then t
1efe0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 he behavior is e
1eff0 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 xactly the same
1f000 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 as calling.** sq
1f010 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a lite3_free(X)..*
1f020 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c * ^sqlite3_reall
1f030 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 oc(X,N) returns
1f040 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d a pointer to a m
1f050 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1f060 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 .** of at least
1f070 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 N bytes in size
1f080 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 or NULL if insuf
1f090 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 ficient memory i
1f0a0 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 s available..**
1f0b0 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a ^If M is the siz
1f0c0 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 e of the prior a
1f0d0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 llocation, then
1f0e0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a min(N,M) bytes.*
1f0f0 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 * of the prior a
1f100 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f llocation are co
1f110 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 pied into the be
1f120 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 ginning of buffe
1f130 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 r returned.** by
1f140 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1f150 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 (X,N) and the pr
1f160 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 ior allocation i
1f170 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 s freed..** ^If
1f180 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1f190 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c X,N) returns NUL
1f1a0 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 L and N is posit
1f1b0 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a ive, then the.**
1f1c0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
1f1d0 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a n is not freed..
1f1e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1f1f0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e e3_realloc64(X,N
1f200 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 ) interfaces wor
1f210 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a ks the same as.*
1f220 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f * sqlite3_reallo
1f230 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 c(X,N) except th
1f240 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 at N is a 64-bit
1f250 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 unsigned intege
1f260 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 r instead.** of
1f270 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 a 32-bit signed
1f280 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e integer..**.** ^
1f290 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 If X is a memory
1f2a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 allocation prev
1f2b0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 iously obtained
1f2c0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c from sqlite3_mal
1f2d0 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 loc(),.** sqlite
1f2e0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 3_malloc64(), sq
1f2f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c lite3_realloc(),
1f300 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c or sqlite3_real
1f310 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a loc64(), then.**
1f320 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 sqlite3_msize(X
1f330 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 ) returns the si
1f340 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 ze of that memor
1f350 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 y allocation in
1f360 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 bytes..** ^The v
1f370 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
1f380 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 sqlite3_msize(X
1f390 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 ) might be large
1f3a0 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 r than the numbe
1f3b0 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 r.** of bytes re
1f3c0 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 quested when X w
1f3d0 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e as allocated. ^
1f3e0 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 If X is a NULL p
1f3f0 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 ointer then.** s
1f400 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 qlite3_msize(X)
1f410 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 returns zero. I
1f420 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f f X points to so
1f430 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 mething that is
1f440 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e not.** the begin
1f450 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 ning of memory a
1f460 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 llocation, or if
1f470 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 it points to a
1f480 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 formerly.** vali
1f490 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 d memory allocat
1f4a0 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 ion that has now
1f4b0 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 been freed, the
1f4c0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a n the behavior.*
1f4d0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 * of sqlite3_msi
1f4e0 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e ze(X) is undefin
1f4f0 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 ed and possibly
1f500 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e harmful..**.** ^
1f510 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 The memory retur
1f520 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d ned by sqlite3_m
1f530 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 alloc(), sqlite3
1f540 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 _realloc(),.** s
1f550 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 qlite3_malloc64(
1f560 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 ), and sqlite3_r
1f570 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 ealloc64().** is
1f580 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 always aligned
1f590 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 to at least an 8
1f5a0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 byte boundary,
1f5b0 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 or to a.** 4 byt
1f5c0 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 e boundary if th
1f5d0 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 e [SQLITE_4_BYTE
1f5e0 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d _ALIGNED_MALLOC]
1f5f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a compile-time.**
1f600 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e option is used.
1f610 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 .**.** In SQLite
1f620 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 version 3.5.0 a
1f630 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 nd 3.5.1, it was
1f640 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 possible to def
1f650 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 ine.** the SQLIT
1f660 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c E_OMIT_MEMORY_AL
1f670 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 LOCATION which w
1f680 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 ould cause the b
1f690 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 uilt-in.** imple
1f6a0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 mentation of the
1f6b0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 se routines to b
1f6c0 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 e omitted. That
1f6d0 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 capability.** i
1f6e0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 s no longer prov
1f6f0 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c ided. Only buil
1f700 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f t-in memory allo
1f710 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 cators can be us
1f720 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 ed..**.** Prior
1f730 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f to SQLite versio
1f740 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 n 3.7.10, the Wi
1f750 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 ndows OS interfa
1f760 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a ce layer called.
1f770 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 ** the system ma
1f780 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 lloc() and free(
1f790 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 ) directly when
1f7a0 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 converting.** fi
1f7b0 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 lenames between
1f7c0 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 the UTF-8 encodi
1f7d0 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 ng used by SQLit
1f7e0 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 e.** and whateve
1f7f0 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 r filename encod
1f800 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 ing is used by t
1f810 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 he particular Wi
1f820 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c ndows.** install
1f830 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 ation. Memory a
1f840 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 llocation errors
1f850 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 were detected,
1f860 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 but.** they were
1f870 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 reported back a
1f880 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 s [SQLITE_CANTOP
1f890 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 EN] or.** [SQLIT
1f8a0 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 E_IOERR] rather
1f8b0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d than [SQLITE_NOM
1f8c0 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 EM]..**.** The p
1f8d0 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 ointer arguments
1f8e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 to [sqlite3_fre
1f8f0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
1f900 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 3_realloc()].**
1f910 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e must be either N
1f920 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e ULL or else poin
1f930 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 ters obtained fr
1f940 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e om a prior.** in
1f950 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c vocation of [sql
1f960 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f ite3_malloc()] o
1f970 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c r [sqlite3_reall
1f980 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a oc()] that have.
1f990 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 ** not yet been
1f9a0 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 released..**.**
1f9b0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
1f9c0 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 must not read or
1f9d0 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 write any part
1f9e0 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 of.** a block of
1f9f0 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 memory after it
1fa00 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 has been releas
1fa10 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c ed using.** [sql
1fa20 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 ite3_free()] or
1fa30 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
1fa40 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ()]..*/.void *sq
1fa50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 lite3_malloc(int
1fa60 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 );.void *sqlite3
1fa70 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 _malloc64(sqlite
1fa80 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 3_uint64);.void
1fa90 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 *sqlite3_realloc
1faa0 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f (void*, int);.vo
1fab0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c id *sqlite3_real
1fac0 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c loc64(void*, sql
1fad0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f ite3_uint64);.vo
1fae0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 id sqlite3_free(
1faf0 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f void*);.sqlite3_
1fb00 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d uint64 sqlite3_m
1fb10 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a size(void*);../*
1fb20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
1fb30 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 mory Allocator S
1fb40 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 tatistics.**.**
1fb50 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 SQLite provides
1fb60 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 these two interf
1fb70 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 aces for reporti
1fb80 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 ng on the status
1fb90 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
1fba0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b te3_malloc()], [
1fbb0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c sqlite3_free()],
1fbc0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
1fbd0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 alloc()].** rout
1fbe0 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d ines, which form
1fbf0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 the built-in me
1fc00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
1fc10 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a subsystem..**.**
1fc20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d ^The [sqlite3_m
1fc30 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f emory_used()] ro
1fc40 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
1fc50 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
1fc60 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 s.** of memory c
1fc70 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e urrently outstan
1fc80 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 ding (malloced b
1fc90 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a ut not freed)..*
1fca0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
1fcb0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
1fcc0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ()] routine retu
1fcd0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a rns the maximum.
1fce0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c ** value of [sql
1fcf0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
1fd00 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 ()] since the hi
1fd10 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a gh-water mark.**
1fd20 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e was last reset.
1fd30 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 ^The values re
1fd40 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
1fd50 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
1fd60 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
1fd70 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
1fd80 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e er()] include an
1fd90 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 y overhead.** ad
1fda0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e ded by SQLite in
1fdb0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 its implementat
1fdc0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
1fdd0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 malloc()],.** bu
1fde0 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 t not overhead a
1fdf0 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 dded by the any
1fe00 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 underlying syste
1fe10 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 m library.** rou
1fe20 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 tines that [sqli
1fe30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 te3_malloc()] ma
1fe40 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 y call..**.** ^T
1fe50 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 he memory high-w
1fe60 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 ater mark is res
1fe70 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e et to the curren
1fe80 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 t value of.** [s
1fe90 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
1fea0 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c ed()] if and onl
1feb0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 y if the paramet
1fec0 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 er to.** [sqlite
1fed0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
1fee0 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 er()] is true.
1fef0 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 ^The value retur
1ff00 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 ned.** by [sqlit
1ff10 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
1ff20 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 ter(1)] is the h
1ff30 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a igh-water mark.*
1ff40 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 * prior to the r
1ff50 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 eset..*/.sqlite3
1ff60 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d _int64 sqlite3_m
1ff70 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 emory_used(void)
1ff80 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 ;.sqlite3_int64
1ff90 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
1ffa0 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 ighwater(int res
1ffb0 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 etFlag);../*.**
1ffc0 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f CAPI3REF: Pseudo
1ffd0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 -Random Number G
1ffe0 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 enerator.**.** S
1fff0 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 QLite contains a
20000 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 high-quality ps
20010 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 eudo-random numb
20020 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 er generator (PR
20030 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 NG) used to.** s
20040 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f elect random [RO
20050 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 WID | ROWIDs] wh
20060 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 en inserting new
20070 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 records into a
20080 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c table that.** al
20090 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c ready uses the l
200a0 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 argest possible
200b0 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 [ROWID]. The PR
200c0 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 NG is also used
200d0 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 for.** the build
200e0 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 -in random() and
200f0 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 randomblob() SQ
20100 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 L functions. Th
20110 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c is interface all
20120 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 ows.** applicati
20130 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 ons to access th
20140 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 e same PRNG for
20150 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a other purposes..
20160 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f **.** ^A call to
20170 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 this routine st
20180 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 ores N bytes of
20190 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 randomness into
201a0 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 buffer P..** ^Th
201b0 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 e P parameter ca
201c0 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e n be a NULL poin
201d0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ter..**.** ^If t
201e0 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 his routine has
201f0 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 not been previou
20200 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 sly called or if
20210 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a the previous.**
20220 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 call had N less
20230 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e than one or a N
20240 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 ULL pointer for
20250 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 P, then the PRNG
20260 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 is.** seeded us
20270 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f ing randomness o
20280 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 btained from the
20290 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 xRandomness met
202a0 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 hod of.** the de
202b0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 fault [sqlite3_v
202c0 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e fs] object..** ^
202d0 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 If the previous
202e0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 call to this rou
202f0 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 tine had an N of
20300 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 1 or more and a
20310 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 .** non-NULL P t
20320 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 hen the pseudo-r
20330 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e andomness is gen
20340 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e erated.** intern
20350 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 ally and without
20360 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 recourse to the
20370 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 [sqlite3_vfs] x
20380 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 Randomness.** me
20390 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 thod..*/.void sq
203a0 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 lite3_randomness
203b0 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 (int N, void *P)
203c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
203d0 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 F: Compile-Time
203e0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 Authorization Ca
203f0 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f llbacks.** METHO
20400 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 D: sqlite3.** KE
20410 59 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 YWORDS: {authori
20420 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a zer callback}.**
20430 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e .** ^This routin
20440 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 e registers an a
20450 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
20460 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 ck with a partic
20470 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 ular.** [databas
20480 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 e connection], s
20490 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 upplied in the f
204a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a irst argument..*
204b0 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 * ^The authorize
204c0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
204d0 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 voked as SQL sta
204e0 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e tements are bein
204f0 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 g compiled.** by
20500 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
20510 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 e()] or its vari
20520 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 ants [sqlite3_pr
20530 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 epare_v2()],.**
20540 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
20550 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v3()], [sqlite3
20560 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 5b _prepare16()], [
20570 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
20580 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 6_v2()],.** and
20590 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
205a0 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 16_v3()]. ^At v
205b0 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 arious.** points
205c0 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 during the comp
205d0 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c ilation process,
205e0 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 as logic is bei
205f0 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f ng created.** to
20600 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 perform various
20610 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 actions, the au
20620 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
20630 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a k is invoked to.
20640 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 ** see if those
20650 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f actions are allo
20660 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f wed. ^The autho
20670 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 rizer callback s
20680 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 hould.** return
20690 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 [SQLITE_OK] to a
206a0 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c llow the action,
206b0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
206c0 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 to disallow the
206d0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 .** specific act
206e0 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 ion but allow th
206f0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
20700 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 to continue to b
20710 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f e.** compiled, o
20720 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 r [SQLITE_DENY]
20730 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 to cause the ent
20740 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ire SQL statemen
20750 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 t to be.** rejec
20760 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f ted with an erro
20770 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 r. ^If the auth
20780 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
20790 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 returns.** any v
207a0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 alue other than
207b0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c [SQLITE_IGNORE],
207c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 [SQLITE_OK], or
207d0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a [SQLITE_DENY].*
207e0 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 * then the [sqli
207f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
20800 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 ] or equivalent
20810 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 call that trigge
20820 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f red.** the autho
20830 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 rizer will fail
20840 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 with an error me
20850 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 ssage..**.** Whe
20860 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 n the callback r
20870 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
20880 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 K], that means t
20890 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 he operation.**
208a0 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e requested is ok.
208b0 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c ^When the call
208c0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 back returns [SQ
208d0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a LITE_DENY], the.
208e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
208f0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 are_v2()] or equ
20900 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 ivalent call tha
20910 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a t triggered the.
20920 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 ** authorizer wi
20930 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 ll fail with an
20940 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 error message ex
20950 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a plaining that.**
20960 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 access is denie
20970 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 d. .**.** ^The f
20980 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
20990 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 o the authorizer
209a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 callback is a c
209b0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 opy of the third
209c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f .** parameter to
209d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 the sqlite3_set
209e0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e _authorizer() in
209f0 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 terface. ^The se
20a00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a cond parameter.*
20a10 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 * to the callbac
20a20 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 k is an integer
20a30 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 [SQLITE_COPY | a
20a40 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 ction code] that
20a50 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 specifies.** th
20a60 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 e particular act
20a70 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 ion to be author
20a80 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 ized. ^The third
20a90 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 through sixth p
20aa0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 arameters.** to
20ab0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 the callback are
20ac0 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 either NULL poi
20ad0 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 nters or zero-te
20ae0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 rminated strings
20af0 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 6e .** that contain
20b00 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 additional deta
20b10 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 ils about the ac
20b20 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f tion to be autho
20b30 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 rized..** Applic
20b40 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 ations must alwa
20b50 79 73 20 62 65 20 70 72 65 70 61 72 65 64 20 74 ys be prepared t
20b60 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 o encounter a NU
20b70 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e LL pointer in an
20b80 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 72 y.** of the thir
20b90 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 69 d through the si
20ba0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f xth parameters o
20bb0 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 f the authorizat
20bc0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a ion callback..**
20bd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 .** ^If the acti
20be0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 on code is [SQLI
20bf0 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 TE_READ].** and
20c00 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
20c10 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e urns [SQLITE_IGN
20c20 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a ORE] then the.**
20c30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
20c40 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 ment] statement
20c50 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 is constructed t
20c60 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 o substitute.**
20c70 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 a NULL value in
20c80 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 place of the tab
20c90 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 le column that w
20ca0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 ould have.** bee
20cb0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 n read if [SQLIT
20cc0 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 E_OK] had been r
20cd0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 eturned. The [S
20ce0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a QLITE_IGNORE].**
20cf0 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 return can be u
20d00 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 sed to deny an u
20d10 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 ntrusted user ac
20d20 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 cess to individu
20d30 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 al.** columns of
20d40 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 a table..** ^Wh
20d50 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72 65 en a table is re
20d60 66 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b 53 ferenced by a [S
20d70 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f ELECT] but no co
20d80 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 0a lumn values are.
20d90 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66 72 6f ** extracted fro
20da0 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28 66 6f m that table (fo
20db0 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 r example in a q
20dc0 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 uery like.** "SE
20dd0 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 LECT count(*) FR
20de0 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74 68 OM tab") then th
20df0 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 e [SQLITE_READ]
20e00 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
20e10 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 ack.** is invoke
20e20 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 20 d once for that
20e30 74 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f 6c table with a col
20e40 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 73 umn name that is
20e50 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
20e60 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 ..** ^If the act
20e70 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c ion code is [SQL
20e80 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 ITE_DELETE] and
20e90 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
20ea0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f urns.** [SQLITE_
20eb0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 IGNORE] then the
20ec0 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 [DELETE] operat
20ed0 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 ion proceeds but
20ee0 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 the.** [truncat
20ef0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 e optimization]
20f00 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 is disabled and
20f10 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c all rows are del
20f20 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c eted individuall
20f30 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 y..**.** An auth
20f40 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 orizer is used w
20f50 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hen [sqlite3_pre
20f60 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 pare | preparing
20f70 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 ].** SQL stateme
20f80 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 nts from an untr
20f90 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f usted source, to
20fa0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
20fb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
20fc0 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f ** do not try to
20fd0 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 access data the
20fe0 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 y are not allowe
20ff0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 d to see, or tha
21000 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a t they do not.**
21010 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 try to execute
21020 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d malicious statem
21030 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 ents that damage
21040 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 the database.
21050 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 For.** example,
21060 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d an application m
21070 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 ay allow a user
21080 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 to enter arbitra
21090 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 ry.** SQL querie
210a0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e s for evaluation
210b0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 by a database.
210c0 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 But the applica
210d0 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 tion does.** not
210e0 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 want the user t
210f0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b o be able to mak
21100 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e e arbitrary chan
21110 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 ges to the.** da
21120 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 tabase. An auth
21130 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 orizer could the
21140 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 n be put in plac
21150 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 e while the.** u
21160 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 ser-entered SQL
21170 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 is being [sqlite
21180 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 3_prepare | prep
21190 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 ared] that.** di
211a0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 sallows everythi
211b0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 ng except [SELEC
211c0 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a T] statements..*
211d0 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e *.** Application
211e0 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 s that need to p
211f0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 rocess SQL from
21200 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
21210 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 s.** might also
21220 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e consider lowerin
21230 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 g resource limit
21240 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 s using [sqlite3
21250 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 _limit()].** and
21260 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 limiting databa
21270 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 se size using th
21280 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e e [max_page_coun
21290 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 t] [PRAGMA].** i
212a0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 n addition to us
212b0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 ing an authorize
212c0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 r..**.** ^(Only
212d0 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 a single authori
212e0 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c zer can be in pl
212f0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 ace on a databas
21300 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
21310 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 at a time. Each
21320 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
21330 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
21340 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a overrides the.**
21350 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 previous call.)
21360 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 ^ ^Disable the
21370 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e authorizer by in
21380 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 stalling a NULL
21390 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 callback..** The
213a0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 authorizer is d
213b0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
213c0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 lt..**.** The au
213d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
213e0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e k must not do an
213f0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
21400 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
21410 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
21420 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
21430 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
21440 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 allback..** Note
21450 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 that [sqlite3_p
21460 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
21470 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
21480 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 ] both modify th
21490 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 eir.** database
214a0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 connections for
214b0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 the meaning of "
214c0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 modify" in this
214d0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a paragraph..**.**
214e0 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f ^When [sqlite3_
214f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 prepare_v2()] is
21500 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 used to prepare
21510 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 a statement, th
21520 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d e.** statement m
21530 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 ight be re-prepa
21540 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 red during [sqli
21550 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 te3_step()] due
21560 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 to a .** schema
21570 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 change. Hence,
21580 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
21590 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 should ensure th
215a0 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 at the.** correc
215b0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c t authorizer cal
215c0 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e lback remains in
215d0 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 place during th
215e0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
215f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 )]..**.** ^Note
21600 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 that the authori
21610 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
21620 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 invoked only dur
21630 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
21640 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 prepare()] or it
21650 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 s variants. Aut
21660 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f horization is no
21670 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 t.** performed d
21680 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 uring statement
21690 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 evaluation in [s
216a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 qlite3_step()],
216b0 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 unless.** as sta
216c0 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 ted in the previ
216d0 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 ous paragraph, s
216e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e qlite3_step() in
216f0 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 vokes.** sqlite3
21700 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f _prepare_v2() to
21710 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 reprepare a sta
21720 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 tement after a s
21730 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f chema change..*/
21740 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 .int sqlite3_set
21750 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 _authorizer(. s
21760 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 qlite3*,. int (
21770 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e *xAuth)(void*,in
21780 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f t,const char*,co
21790 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
217a0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
217b0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 *),. void *pUse
217c0 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 rData.);../*.**
217d0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 CAPI3REF: Author
217e0 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 izer Return Code
217f0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c s.**.** The [sql
21800 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
21810 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 zer | authorizer
21820 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
21830 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 on] must.** retu
21840 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 rn either [SQLIT
21850 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 E_OK] or one of
21860 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 these two consta
21870 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 nts in order.**
21880 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 to signal SQLite
21890 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
218a0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 the action is pe
218b0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 rmitted. See th
218c0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 e.** [sqlite3_se
218d0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
218e0 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 uthorizer docume
218f0 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 ntation] for add
21900 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 itional.** infor
21910 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f mation..**.** No
21920 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 te that SQLITE_I
21930 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 GNORE is also us
21940 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 ed as a [conflic
21950 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 t resolution mod
21960 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 e].** returned f
21970 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 rom the [sqlite3
21980 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 _vtab_on_conflic
21990 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a t()] interface..
219a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
219b0 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 E_DENY 1 /*
219c0 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 Abort the SQL st
219d0 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 atement with an
219e0 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 error */.#define
219f0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 SQLITE_IGNORE 2
21a00 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f /* Don't allo
21a10 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f w access, but do
21a20 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 n't generate an
21a30 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 error */../*.**
21a40 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 CAPI3REF: Author
21a50 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 izer Action Code
21a60 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c s.**.** The [sql
21a70 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
21a80 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 zer()] interface
21a90 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c registers a cal
21aa0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a lback function.*
21ab0 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 * that is invoke
21ac0 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 d to authorize c
21ad0 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 ertain SQL state
21ae0 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 ment actions. T
21af0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 he.** second par
21b00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 ameter to the ca
21b10 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 llback is an int
21b20 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 eger code that s
21b30 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 pecifies.** what
21b40 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 action is being
21b50 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 authorized. Th
21b60 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 ese are the inte
21b70 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 ger action codes
21b80 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 that.** the aut
21b90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
21ba0 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a may be passed..
21bb0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 **.** These acti
21bc0 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 on code values s
21bd0 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 ignify what kind
21be0 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 of operation is
21bf0 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 to be.** author
21c00 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 ized. The 3rd a
21c10 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 nd 4th parameter
21c20 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 s to the authori
21c30 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 zation.** callba
21c40 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c ck function will
21c50 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f be parameters o
21c60 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 r NULL depending
21c70 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 on which of the
21c80 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 se.** codes is u
21c90 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
21ca0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 d parameter. ^(
21cb0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 The 5th paramete
21cc0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 r to the.** auth
21cd0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
21ce0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
21cf0 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 he database ("ma
21d00 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 in", "temp",.**
21d10 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 etc.) if applica
21d20 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 ble.)^ ^The 6th
21d30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
21d40 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
21d50 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 lback.** is the
21d60 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 name of the inne
21d70 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f r-most trigger o
21d80 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 r view that is r
21d90 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a esponsible for.*
21da0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 * the access att
21db0 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 empt or NULL if
21dc0 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 this access atte
21dd0 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 mpt is directly
21de0 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 from.** top-leve
21df0 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f l SQL code..*/./
21e00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21e10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21e20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 *********** 3rd
21e30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 ************ 4th
21e40 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 ***********/.#d
21e50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
21e60 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 ATE_INDEX
21e70 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 1 /* Index
21e80 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
21e90 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
21ea0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
21eb0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 TE_TABLE
21ec0 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 2 /* Table N
21ed0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
21ee0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
21ef0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
21f00 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 E_TEMP_INDEX
21f10 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 3 /* Index Na
21f20 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
21f30 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
21f40 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
21f50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 _TEMP_TABLE
21f60 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 4 /* Table Nam
21f70 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
21f80 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
21f90 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
21fa0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 TEMP_TRIGGER 5
21fb0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
21fc0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
21fd0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
21fe0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
21ff0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 EMP_VIEW 6
22000 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
22010 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
22020 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22030 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 SQLITE_CREATE_TR
22040 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 IGGER 7
22050 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
22060 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
22070 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
22080 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 QLITE_CREATE_VIE
22090 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 W 8
220a0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
220b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
220c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
220d0 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 LITE_DELETE
220e0 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 9 /
220f0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
22100 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
22110 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22120 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 ITE_DROP_INDEX
22130 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 10 /*
22140 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
22150 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
22160 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22170 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 TE_DROP_TABLE
22180 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 11 /*
22190 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
221a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
221b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
221c0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 E_DROP_TEMP_INDE
221d0 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 X 12 /* I
221e0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
221f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
22200 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22210 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 _DROP_TEMP_TABLE
22220 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 13 /* Ta
22230 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
22240 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
22250 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22260 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 DROP_TEMP_TRIGGE
22270 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 R 14 /* Tri
22280 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
22290 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
222a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
222b0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 ROP_TEMP_VIEW
222c0 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 15 /* View
222d0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
222e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
222f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
22300 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 OP_TRIGGER
22310 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 16 /* Trigg
22320 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
22330 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
22340 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
22350 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 P_VIEW
22360 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 17 /* View N
22370 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
22380 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
22390 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 fine SQLITE_INSE
223a0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 RT
223b0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 18 /* Table N
223c0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
223d0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
223e0 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d ine SQLITE_PRAGM
223f0 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 A
22400 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 19 /* Pragma N
22410 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 ame 1st arg
22420 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 or NULL */.#defi
22430 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 ne SQLITE_READ
22440 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
22450 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 0 /* Table Nam
22460 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 e Column Na
22470 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
22480 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 e SQLITE_SELECT
22490 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 21
224a0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 /* NULL
224b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
224c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
224d0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 SQLITE_TRANSACT
224e0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 ION 22
224f0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 /* Operation
22500 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
22510 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22520 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 SQLITE_UPDATE
22530 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 23
22540 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
22550 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 Column Name
22560 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
22570 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 QLITE_ATTACH
22580 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 24
22590 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 /* Filename
225a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
225b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
225c0 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 LITE_DETACH
225d0 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 25 /
225e0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 * Database Name
225f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
22600 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22610 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 ITE_ALTER_TABLE
22620 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 26 /*
22630 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 Database Name
22640 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
22650 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22660 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 TE_REINDEX
22670 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 27 /*
22680 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
22690 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
226a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
226b0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 E_ANALYZE
226c0 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 28 /* T
226d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
226e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
226f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22700 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 _CREATE_VTABLE
22710 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 29 /* Ta
22720 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f ble Name Mo
22730 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f dule Name */
22740 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22750 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 DROP_VTABLE
22760 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 30 /* Tab
22770 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 le Name Mod
22780 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a ule Name */.
22790 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
227a0 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 UNCTION
227b0 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 31 /* NULL
227c0 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 Func
227d0 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 tion Name */.#
227e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 define SQLITE_SA
227f0 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 VEPOINT
22800 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 32 /* Opera
22810 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 tion Savep
22820 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 oint Name */.#d
22830 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 efine SQLITE_COP
22840 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 Y
22850 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 0 /* No lon
22860 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 ger used */.#def
22870 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 ine SQLITE_RECUR
22880 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 SIVE
22890 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 33 /* NULL
228a0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 NULL
228b0 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a */../*.*
228c0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 * CAPI3REF: Trac
228d0 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e ing And Profilin
228e0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d g Functions.** M
228f0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
22900 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
22910 6e 65 73 20 61 72 65 20 64 65 70 72 65 63 61 74 nes are deprecat
22920 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c ed. Use the [sql
22930 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d ite3_trace_v2()]
22940 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e interface.** in
22950 73 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75 stead of the rou
22960 74 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 20 tines described
22970 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 here..**.** Thes
22980 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 e routines regis
22990 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e ter callback fun
229a0 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 ctions that can
229b0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 be used for.** t
229c0 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 racing and profi
229d0 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 ling the executi
229e0 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d on of SQL statem
229f0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ents..**.** ^The
22a00 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
22a10 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 on registered by
22a20 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 sqlite3_trace()
22a30 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a is invoked at.*
22a40 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 * various times
22a50 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 when an SQL stat
22a60 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 ement is being r
22a70 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 un by [sqlite3_s
22a80 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 tep()]..** ^The
22a90 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
22aa0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
22ab0 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 ked with a UTF-8
22ac0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
22ad0 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 e.** SQL stateme
22ae0 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 nt text as the s
22af0 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 tatement first b
22b00 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e egins executing.
22b10 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c .** ^(Additional
22b20 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 sqlite3_trace()
22b30 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 callbacks might
22b40 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 occur.** as eac
22b50 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 h triggered subp
22b60 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 rogram is entere
22b70 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b d. The callback
22b80 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a s for triggers.*
22b90 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d * contain a UTF-
22ba0 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 8 SQL comment th
22bb0 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 at identifies th
22bc0 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a e trigger.)^.**.
22bd0 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** The [SQLITE_T
22be0 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d RACE_SIZE_LIMIT]
22bf0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
22c00 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 tion can be used
22c10 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 to limit.** the
22c20 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e length of [boun
22c30 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 d parameter] exp
22c40 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 ansion in the ou
22c50 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f tput of sqlite3_
22c60 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e trace()..**.** ^
22c70 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e The callback fun
22c80 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 ction registered
22c90 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 by sqlite3_prof
22ca0 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ile() is invoked
22cb0 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 .** as each SQL
22cc0 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 statement finish
22cd0 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c es. ^The profil
22ce0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 e callback conta
22cf0 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 ins.** the origi
22d00 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 nal statement te
22d10 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 xt and an estima
22d20 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b te of wall-clock
22d30 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 time.** of how
22d40 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d long that statem
22d50 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e ent took to run.
22d60 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 ^The profile c
22d70 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 allback.** time
22d80 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e is in units of n
22d90 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 anoseconds, howe
22da0 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 ver the current
22db0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a implementation.*
22dc0 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c * is only capabl
22dd0 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 e of millisecond
22de0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 resolution so t
22df0 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 he six least sig
22e00 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 nificant.** digi
22e10 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 ts in the time a
22e20 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 re meaningless.
22e30 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 Future versions
22e40 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 of SQLite.** mi
22e50 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 ght provide grea
22e60 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f ter resolution o
22e70 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 n the profiler c
22e80 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a allback. The.**
22e90 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 sqlite3_profile
22ea0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 () function is c
22eb0 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 onsidered experi
22ec0 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a mental and is.**
22ed0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
22ee0 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 ge in future ver
22ef0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e sions of SQLite.
22f00 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 .*/.SQLITE_DEPRE
22f10 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 CATED void *sqli
22f20 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 te3_trace(sqlite
22f30 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 3*,. void(*xTr
22f40 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 ace)(void*,const
22f50 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b char*), void*);
22f60 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 .SQLITE_DEPRECAT
22f70 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 ED void *sqlite3
22f80 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 _profile(sqlite3
22f90 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f *,. void(*xPro
22fa0 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 file)(void*,cons
22fb0 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f t char*,sqlite3_
22fc0 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b uint64), void*);
22fd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
22fe0 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e : SQL Trace Even
22ff0 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f t Codes.** KEYWO
23000 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 RDS: SQLITE_TRAC
23010 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f E.**.** These co
23020 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 nstants identify
23030 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e classes of even
23040 74 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d ts that can be m
23050 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e onitored.** usin
23060 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 g the [sqlite3_t
23070 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 race_v2()] traci
23080 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 ng logic. The t
23090 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a hird argument.**
230a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 to [sqlite3_tra
230b0 63 65 5f 76 32 28 29 5d 20 69 73 20 61 6e 20 4f ce_v2()] is an O
230c0 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e R-ed combination
230d0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 of one or more
230e0 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 of.** the follow
230f0 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 ing constants.
23100 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
23110 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 ent to the trace
23120 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
23130 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
23140 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a wing constants..
23150 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e **.** New tracin
23160 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 g constants may
23170 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
23180 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a re releases..**.
23190 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c ** ^A trace call
231a0 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72 back has four ar
231b0 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 guments: xCallba
231c0 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 ck(T,C,P,X)..**
231d0 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 ^The T argument
231e0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e is one of the in
231f0 74 65 67 65 72 20 74 79 70 65 20 63 6f 64 65 73 teger type codes
23200 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 above..** ^The
23210 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 C argument is a
23220 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 copy of the cont
23230 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73 ext pointer pass
23240 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 ed in as the.**
23250 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 fourth argument
23260 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 to [sqlite3_trac
23270 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 e_v2()]..** The
23280 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 P and X argument
23290 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 s are pointers w
232a0 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 hose meanings de
232b0 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a pend on T..**.**
232c0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 <dl>.** [[SQLIT
232d0 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c E_TRACE_STMT]] <
232e0 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f dt>SQLITE_TRACE_
232f0 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 STMT</dt>.** <dd
23300 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 >^An SQLITE_TRAC
23310 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 E_STMT callback
23320 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 is invoked when
23330 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 a prepared state
23340 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 ment.** first be
23350 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 gins running and
23360 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68 possibly at oth
23370 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 er times during
23380 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e the.** execution
23390 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64 of the prepared
233a0 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 statement, such
233b0 20 61 73 20 61 74 20 74 68 65 20 73 74 61 72 74 as at the start
233c0 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 of each.** trig
233d0 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 ger subprogram.
233e0 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 ^The P argument
233f0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
23400 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
23410 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 statement]. ^Th
23420 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 e X argument is
23430 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 a pointer to a s
23440 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 tring which.** i
23450 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64 s the unexpanded
23460 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65 SQL text of the
23470 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
23480 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f ent or an SQL co
23490 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 mment .** that i
234a0 6e 64 69 63 61 74 65 73 20 74 68 65 20 69 6e 76 ndicates the inv
234b0 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 ocation of a tri
234c0 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c gger. ^The call
234d0 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 back can compute
234e0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78 .** the same tex
234f0 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 t that would hav
23500 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 e been returned
23510 62 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 by the legacy [s
23520 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a qlite3_trace()].
23530 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 ** interface by
23540 75 73 69 6e 67 20 74 68 65 20 58 20 61 72 67 75 using the X argu
23550 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69 ment when X begi
23560 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 ns with "--" and
23570 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 invoking.** [sq
23580 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 lite3_expanded_s
23590 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65 ql(P)] otherwise
235a0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ..**.** [[SQLITE
235b0 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d _TRACE_PROFILE]]
235c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 <dt>SQLITE_TRAC
235d0 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a E_PROFILE</dt>.*
235e0 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 * <dd>^An SQLITE
235f0 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 _TRACE_PROFILE c
23600 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73 allback provides
23610 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 approximately t
23620 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 he same.** infor
23630 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f mation as is pro
23640 76 69 64 65 64 20 62 79 20 74 68 65 20 5b 73 71 vided by the [sq
23650 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d lite3_profile()]
23660 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 callback..** ^T
23670 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 he P argument is
23680 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
23690 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
236a0 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a ement] and the.*
236b0 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 * X argument poi
236c0 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20 nts to a 64-bit
236d0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 integer which is
236e0 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f the estimated o
236f0 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 f.** the number
23700 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 of nanosecond th
23710 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 at the prepared
23720 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 statement took t
23730 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 o run..** ^The S
23740 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 QLITE_TRACE_PROF
23750 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ILE callback is
23760 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 invoked when the
23770 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 statement finis
23780 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c hes..**.** [[SQL
23790 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 ITE_TRACE_ROW]]
237a0 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 <dt>SQLITE_TRACE
237b0 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 _ROW</dt>.** <dd
237c0 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 >^An SQLITE_TRAC
237d0 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 E_ROW callback i
237e0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 s invoked whenev
237f0 65 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a er a prepared.**
23800 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 statement gener
23810 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f ates a single ro
23820 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a w of result. .*
23830 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e * ^The P argumen
23840 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
23850 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 o the [prepared
23860 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 statement] and t
23870 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 he.** X argument
23880 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a is unused..**.*
23890 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 * [[SQLITE_TRACE
238a0 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c _CLOSE]] <dt>SQL
238b0 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c ITE_TRACE_CLOSE<
238c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 /dt>.** <dd>^An
238d0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f SQLITE_TRACE_CLO
238e0 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 SE callback is i
238f0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61 nvoked when a da
23900 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
23910 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 tion closes..**
23920 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 ^The P argument
23930 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
23940 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
23950 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 nnection] object
23960 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72 .** and the X ar
23970 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 gument is unused
23980 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 ..** </dl>.*/.#d
23990 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 efine SQLITE_TRA
239a0 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78 CE_STMT 0x
239b0 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 01.#define SQLIT
239c0 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 E_TRACE_PROFILE
239d0 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 0x02.#define
239e0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 SQLITE_TRACE_ROW
239f0 20 20 20 20 20 20 20 20 30 78 30 34 0a 23 64 65 0x04.#de
23a00 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 fine SQLITE_TRAC
23a10 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30 E_CLOSE 0x0
23a20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 8../*.** CAPI3RE
23a30 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f F: SQL Trace Hoo
23a40 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c k.** METHOD: sql
23a50 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ite3.**.** ^The
23a60 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 sqlite3_trace_v2
23a70 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 (D,M,X,P) interf
23a80 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ace registers a
23a90 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a trace callback.*
23aa0 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 * function X aga
23ab0 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20 63 inst [database c
23ac0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 onnection] D, us
23ad0 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73 ing property mas
23ae0 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 k M.** and conte
23af0 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e xt pointer P. ^
23b00 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63 If the X callbac
23b10 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 k is.** NULL or
23b20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 if the M mask is
23b30 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 zero, then trac
23b40 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e ing is disabled.
23b50 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d The.** M argum
23b60 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 ent should be th
23b70 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20 e bitwise OR-ed
23b80 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a combination of.*
23b90 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b * zero or more [
23ba0 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f SQLITE_TRACE] co
23bb0 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e nstants..**.** ^
23bc0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 Each call to eit
23bd0 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 her sqlite3_trac
23be0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 e() or sqlite3_t
23bf0 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69 race_v2() overri
23c00 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 des .** (cancels
23c10 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c ) any prior call
23c20 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 s to sqlite3_tra
23c30 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f ce() or sqlite3_
23c40 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a trace_v2()..**.*
23c50 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63 * ^The X callbac
23c60 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 k is invoked whe
23c70 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65 never any of the
23c80 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69 events identifi
23c90 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d ed by .** mask M
23ca0 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e occur. ^The in
23cb0 74 65 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c teger return val
23cc0 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c ue from the call
23cd0 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c back is currentl
23ce0 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 y.** ignored, th
23cf0 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20 63 68 ough this may ch
23d00 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 ange in future r
23d10 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 eleases. Callba
23d20 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 ck.** implementa
23d30 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 tions should ret
23d40 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 urn zero to ensu
23d50 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74 re future compat
23d60 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e ibility..**.** ^
23d70 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b A trace callback
23d80 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 is invoked with
23d90 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a four arguments:
23da0 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c callback(T,C,P,
23db0 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 X)..** ^The T ar
23dc0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 gument is one of
23dd0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 the [SQLITE_TRA
23de0 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 CE].** constants
23df0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79 to indicate why
23e00 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 the callback wa
23e10 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 s invoked..** ^T
23e20 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 he C argument is
23e30 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 a copy of the c
23e40 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a ontext pointer..
23e50 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 ** The P and X a
23e60 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 rguments are poi
23e70 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e nters whose mean
23e80 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 ings depend on T
23e90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
23ea0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69 te3_trace_v2() i
23eb0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 nterface is inte
23ec0 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20 nded to replace
23ed0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e the legacy.** in
23ee0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 terfaces [sqlite
23ef0 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 3_trace()] and [
23f00 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 sqlite3_profile(
23f10 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63 )], both of whic
23f20 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61 h.** are depreca
23f30 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ted..*/.int sqli
23f40 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 te3_trace_v2(.
23f50 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 sqlite3*,. unsi
23f60 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e gned uMask,. in
23f70 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e t(*xCallback)(un
23f80 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 signed,void*,voi
23f90 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 d*,void*),. voi
23fa0 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a d *pCtx.);../*.*
23fb0 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 * CAPI3REF: Quer
23fc0 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 y Progress Callb
23fd0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 acks.** METHOD:
23fe0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
23ff0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 he sqlite3_progr
24000 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c ess_handler(D,N,
24010 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 X,P) interface c
24020 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 auses the callba
24030 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 ck.** function X
24040 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 to be invoked p
24050 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 eriodically duri
24060 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 ng long running
24070 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c calls to.** [sql
24080 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 ite3_exec()], [s
24090 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 qlite3_step()] a
240a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f nd [sqlite3_get_
240b0 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 table()] for.**
240c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
240d0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 ion D. An examp
240e0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a le use for this.
240f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
24100 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 to keep a GUI up
24110 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c dated during a l
24120 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a arge query..**.*
24130 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 * ^The parameter
24140 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 P is passed thr
24150 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 ough as the only
24160 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
24170 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 e .** callback f
24180 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 unction X. ^The
24190 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 parameter N is
241a0 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 the approximate
241b0 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 number of .** [v
241c0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 irtual machine i
241d0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 nstructions] tha
241e0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 t are evaluated
241f0 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 between successi
24200 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e ve.** invocation
24210 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 s of the callbac
24220 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c k X. ^If N is l
24230 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 ess than one the
24240 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a n the progress.*
24250 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 * handler is dis
24260 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e abled..**.** ^On
24270 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 ly a single prog
24280 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 ress handler may
24290 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f be defined at o
242a0 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b ne time per.** [
242b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
242c0 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 ion]; setting a
242d0 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e new progress han
242e0 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 dler cancels the
242f0 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 .** old one. ^S
24300 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 etting parameter
24310 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 X to NULL disab
24320 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 les the progress
24330 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 handler..** ^Th
24340 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
24350 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 er is also disab
24360 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e led by setting N
24370 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 to a value less
24380 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a .** than 1..**.*
24390 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 * ^If the progre
243a0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 ss callback retu
243b0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
243c0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a e operation is.*
243d0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 * interrupted.
243e0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e This feature can
243f0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c be used to impl
24400 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 ement a.** "Canc
24410 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 el" button on a
24420 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 GUI progress dia
24430 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 log box..**.** T
24440 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
24450 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 ler callback mus
24460 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
24470 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
24480 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
24490 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
244a0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 at invoked the p
244b0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e rogress handler.
244c0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
244d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
244e0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
244f0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
24500 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
24510 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
24520 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
24530 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
24540 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
24550 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 h..**.*/.void sq
24560 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 lite3_progress_h
24570 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c andler(sqlite3*,
24580 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 int, int(*)(voi
24590 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a d*), void*);../*
245a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 .** CAPI3REF: Op
245b0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 ening A New Data
245c0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a base Connection.
245d0 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 ** CONSTRUCTOR:
245e0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
245f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 hese routines op
24600 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 en an SQLite dat
24610 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 abase file as sp
24620 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a ecified by the .
24630 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 ** filename argu
24640 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e ment. ^The filen
24650 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ame argument is
24660 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 interpreted as U
24670 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 TF-8 for.** sqli
24680 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 te3_open() and s
24690 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
246a0 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 and as UTF-16 i
246b0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 n the native byt
246c0 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 e.** order for s
246d0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e qlite3_open16().
246e0 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 ^(A [database c
246f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
24700 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 e is usually.**
24710 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 returned in *ppD
24720 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 b, even if an er
24730 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 ror occurs. The
24740 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 only exception
24750 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 is that.** if SQ
24760 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 Lite is unable t
24770 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 o allocate memor
24780 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 y to hold the [s
24790 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a qlite3] object,.
247a0 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 ** a NULL will b
247b0 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a e written into *
247c0 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 ppDb instead of
247d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
247e0 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 [sqlite3].** ob
247f0 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 ject.)^ ^(If the
24800 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
24810 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 ned (and/or crea
24820 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c ted) successfull
24830 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 y, then.** [SQLI
24840 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e TE_OK] is return
24850 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 ed. Otherwise a
24860 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
24870 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 s returned.)^ ^T
24880 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 he.** [sqlite3_e
24890 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c rrmsg()] or [sql
248a0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d ite3_errmsg16()]
248b0 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 routines can be
248c0 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a used to obtain.
248d0 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 ** an English la
248e0 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 nguage descripti
248f0 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 on of the error
24900 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c following a fail
24910 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 ure of any.** of
24920 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 the sqlite3_ope
24930 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a n() routines..**
24940 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 .** ^The default
24950 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 encoding will b
24960 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 e UTF-8 for data
24970 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73 bases created us
24980 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f ing.** sqlite3_o
24990 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
249a0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 _open_v2(). ^Th
249b0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 e default encodi
249c0 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 ng for databases
249d0 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e .** created usin
249e0 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 g sqlite3_open16
249f0 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 () will be UTF-1
24a00 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 6 in the native
24a10 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a byte order..**.*
24a20 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 * Whether or not
24a30 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
24a40 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e when it is open
24a50 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a ed, resources.**
24a60 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
24a70 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
24a80 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
24a90 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 e should be rele
24aa0 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 ased by.** passi
24ab0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 ng it to [sqlite
24ac0 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 3_close()] when
24ad0 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 it is no longer
24ae0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
24af0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e The sqlite3_open
24b00 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 _v2() interface
24b10 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 works like sqlit
24b20 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 e3_open().** exc
24b30 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 ept that it acce
24b40 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e pts two addition
24b50 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f al parameters fo
24b60 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e r additional con
24b70 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 trol.** over the
24b80 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f new database co
24b90 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 nnection. ^(The
24ba0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
24bb0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f to.** sqlite3_o
24bc0 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b pen_v2() can tak
24bd0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 e one of.** the
24be0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 following three
24bf0 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c values, optional
24c00 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 ly combined with
24c10 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 the .** [SQLITE
24c20 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 _OPEN_NOMUTEX],
24c30 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c [SQLITE_OPEN_FUL
24c40 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 LMUTEX], [SQLITE
24c50 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
24c60 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f E],.** [SQLITE_O
24c70 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 PEN_PRIVATECACHE
24c80 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 ], and/or [SQLIT
24c90 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 E_OPEN_URI] flag
24ca0 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a s:)^.**.** <dl>.
24cb0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 ** ^(<dt>[SQLITE
24cc0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c _OPEN_READONLY]<
24cd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
24ce0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
24cf0 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 ed in read-only
24d00 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 mode. If the da
24d10 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a tabase does not.
24d20 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 ** already exist
24d30 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 , an error is re
24d40 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a turned.</dd>)^.*
24d50 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 *.** ^(<dt>[SQLI
24d60 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
24d70 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 E]</dt>.** <dd>T
24d80 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
24d90 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e pened for readin
24da0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 g and writing if
24db0 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 possible, or re
24dc0 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 ading.** only if
24dd0 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 the file is wri
24de0 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 te protected by
24df0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
24e00 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 stem. In either
24e10 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 .** case the dat
24e20 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 abase must alrea
24e30 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 dy exist, otherw
24e40 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 ise an error is
24e50 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e returned.</dd>)^
24e60 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 .**.** ^(<dt>[SQ
24e70 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
24e80 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f ITE] | [SQLITE_O
24e90 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e PEN_CREATE]</dt>
24ea0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 .** <dd>The data
24eb0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
24ec0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 or reading and w
24ed0 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 riting, and is c
24ee0 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 reated if.** it
24ef0 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 does not already
24f00 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 exist. This is
24f10 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 the behavior tha
24f20 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 t is always used
24f30 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
24f40 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
24f50 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 e3_open16().</dd
24f60 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a >)^.** </dl>.**.
24f70 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 ** If the 3rd pa
24f80 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
24f90 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
24fa0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a not one of the.*
24fb0 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 * combinations s
24fc0 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f hown above optio
24fd0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 nally combined w
24fe0 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 ith other.** [SQ
24ff0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
25000 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e LY | SQLITE_OPEN
25010 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e _* bits].** then
25020 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
25030 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
25040 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 * ^If the [SQLIT
25050 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 E_OPEN_NOMUTEX]
25060 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 flag is set, the
25070 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
25080 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 onnection.** ope
25090 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d ns in the multi-
250a0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e thread [threadin
250b0 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 g mode] as long
250c0 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 as the single-th
250d0 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 read.** mode has
250e0 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 not been set at
250f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 compile-time or
25100 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 start-time. ^I
25110 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 f the.** [SQLITE
25120 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d _OPEN_FULLMUTEX]
25130 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 flag is set the
25140 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
25150 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a onnection opens.
25160 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c ** in the serial
25170 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 ized [threading
25180 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e mode] unless sin
25190 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a gle-thread was.*
251a0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c * previously sel
251b0 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 ected at compile
251c0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 -time or start-t
251d0 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ime..** ^The [SQ
251e0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
251f0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 CACHE] flag caus
25200 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
25210 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 connection to be
25220 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 .** eligible to
25230 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 use [shared cach
25240 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c e mode], regardl
25250 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
25260 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 r not shared.**
25270 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 cache is enabled
25280 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
25290 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 enable_shared_ca
252a0 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a che()]. ^The.**
252b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 [SQLITE_OPEN_PR
252c0 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 IVATECACHE] flag
252d0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 causes the data
252e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
252f0 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 to not.** partic
25300 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 ipate in [shared
25310 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 cache mode] eve
25320 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c n if it is enabl
25330 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ed..**.** ^The f
25340 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
25350 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
25360 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 v2() is the name
25370 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
25380 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 te3_vfs] object
25390 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 that defines the
253a0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
253b0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 m interface that
253c0 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 .** the new data
253d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
253e0 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 should use. ^If
253f0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
25400 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 meter is.** a NU
25410 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
25420 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c the default [sql
25430 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
25440 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
25450 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 ^If the filename
25460 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 is ":memory:",
25470 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 then a private,
25480 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d temporary in-mem
25490 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 ory database.**
254a0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 is created for t
254b0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 he connection.
254c0 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 ^This in-memory
254d0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 database will va
254e0 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 nish when.** the
254f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
25500 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 tion is closed.
25510 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 Future versions
25520 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 of SQLite might
25530 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 .** make use of
25540 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 additional speci
25550 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 al filenames tha
25560 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 t begin with the
25570 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a ":" character..
25580 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 ** It is recomme
25590 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 nded that when a
255a0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 database filena
255b0 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 me actually does
255c0 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 begin with.** a
255d0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 ":" character y
255e0 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 ou should prefix
255f0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 the filename wi
25600 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 th a pathname su
25610 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f ch as.** "./" to
25620 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 avoid ambiguity
25630 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
25640 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 filename is an e
25650 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 mpty string, the
25660 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d n a private, tem
25670 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 porary.** on-dis
25680 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 k database will
25690 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 be created. ^Th
256a0 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 is private datab
256b0 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 ase will be.** a
256c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c utomatically del
256d0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 eted as soon as
256e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
256f0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 nection is close
25700 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 d..**.** [[URI f
25710 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 ilenames in sqli
25720 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 te3_open()]] <h3
25730 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f >URI Filenames</
25740 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 h3>.**.** ^If [U
25750 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 RI filename] int
25760 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 erpretation is e
25770 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 nabled, and the
25780 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
25790 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 t.** begins with
257a0 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 "file:", then t
257b0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 he filename is i
257c0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
257d0 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c URI. ^URI.** fil
257e0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 ename interpreta
257f0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 tion is enabled
25800 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f if the [SQLITE_O
25810 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 PEN_URI] flag is
25820 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 .** set in the f
25830 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 ourth argument t
25840 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
25850 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 2(), or if it ha
25860 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 s.** been enable
25870 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 d globally using
25880 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e the [SQLITE_CON
25890 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 FIG_URI] option
258a0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c with the.** [sql
258b0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d ite3_config()] m
258c0 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 ethod or by the
258d0 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d [SQLITE_USE_URI]
258e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
258f0 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 tion..** As of S
25900 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
25910 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 7.7, URI filenam
25920 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e e interpretation
25930 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a is turned off.*
25940 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 * by default, bu
25950 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 t future release
25960 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 s of SQLite migh
25970 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c t enable URI fil
25980 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 ename.** interpr
25990 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 etation by defau
259a0 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 lt. See "[URI f
259b0 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 ilenames]" for a
259c0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
259d0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
259e0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 URI filenames ar
259f0 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 e parsed accordi
25a00 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 ng to RFC 3986.
25a10 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 ^If the URI cont
25a20 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f ains an.** autho
25a30 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 rity, then it mu
25a40 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 st be either an
25a50 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 empty string or
25a60 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 the string .** "
25a70 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 localhost". ^If
25a80 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 the authority is
25a90 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 not an empty st
25aa0 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f ring or "localho
25ab0 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f st", an .** erro
25ac0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f r is returned to
25ad0 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 the caller. ^Th
25ae0 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f e fragment compo
25af0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 nent of a URI, i
25b00 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 f .** present, i
25b10 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a s ignored..**.**
25b20 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 ^SQLite uses th
25b30 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 e path component
25b40 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 of the URI as t
25b50 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
25b60 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 isk file.** whic
25b70 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 h contains the d
25b80 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 atabase. ^If the
25b90 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 path begins wit
25ba0 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 h a '/' characte
25bb0 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 r, .** then it i
25bc0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
25bd0 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 an absolute pat
25be0 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 h. ^If the path
25bf0 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a does not begin .
25c00 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d ** with a '/' (m
25c10 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 eaning that the
25c20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f authority sectio
25c30 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f n is omitted fro
25c40 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 m the URI).** th
25c50 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 en the path is i
25c60 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
25c70 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a relative path. .
25c80 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c ** ^(On windows,
25c90 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f the first compo
25ca0 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c nent of an absol
25cb0 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 ute path .** is
25cc0 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 a drive specific
25cd0 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 ation (e.g. "C:"
25ce0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 ).)^.**.** [[cor
25cf0 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 e URI query para
25d00 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 meters]].** The
25d10 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 query component
25d20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e of a URI may con
25d30 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 tain parameters
25d40 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 that are interpr
25d50 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 eted.** either b
25d60 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c y SQLite itself,
25d70 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 or by a [VFS |
25d80 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 custom VFS imple
25d90 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 mentation]..** S
25da0 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 QLite and its bu
25db0 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 ilt-in [VFSes] i
25dc0 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 nterpret the.**
25dd0 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 following query
25de0 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a parameters:.**.*
25df0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e * <ul>.** <li>
25e00 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 <b>vfs</b>: ^Th
25e10 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 e "vfs" paramete
25e20 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f r may be used to
25e30 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d specify the nam
25e40 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 e of.** a VF
25e50 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 S object that pr
25e60 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 ovides the opera
25e70 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 ting system inte
25e80 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c rface that shoul
25e90 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 d.** be used
25ea0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 to access the d
25eb0 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 atabase file on
25ec0 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f disk. ^If this o
25ed0 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a ption is set to.
25ee0 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 ** an empty
25ef0 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 string the defau
25f00 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 lt VFS object is
25f10 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 used. ^Specifyi
25f20 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a ng an unknown.**
25f30 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 VFS is an e
25f40 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 rror. ^If sqlite
25f50 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 3_open_v2() is u
25f60 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 sed and the vfs
25f70 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 option is.**
25f80 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 present, then t
25f90 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 he VFS specified
25fa0 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 by the option t
25fb0 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 akes precedence
25fc0 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 over.** the
25fd0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 value passed as
25fe0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
25ff0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
26000 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a open_v2()..**.**
26010 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c <li> <b>mode<
26020 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 /b>: ^(The mode
26030 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
26040 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 set to either "
26050 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 ro", "rw",.**
26060 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d "rwc", or "mem
26070 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 ory". Attempting
26080 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e to set it to an
26090 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 y other value is
260a0 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 .** an error
260b0 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 )^. .** ^If
260c0 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 "ro" is specifie
260d0 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 d, then the data
260e0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
260f0 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a or read-only .**
26100 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 access, jus
26110 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c t as if the [SQL
26120 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
26130 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e Y] flag had been
26140 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 set in the .**
26150 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 third argume
26160 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 nt to sqlite3_op
26170 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 en_v2(). ^If the
26180 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 mode option is
26190 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 set to .** "
261a0 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 rw", then the da
261b0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
261c0 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 for read-write
261d0 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 (but not create)
261e0 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c .** access,
261f0 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 as if SQLITE_OP
26200 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 EN_READWRITE (bu
26210 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 t not SQLITE_OPE
26220 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a N_CREATE) had .*
26230 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 * been set.
26240 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 ^Value "rwc" is
26250 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 equivalent to se
26260 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 tting both .**
26270 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 SQLITE_OPEN_R
26280 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c EADWRITE and SQL
26290 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e ITE_OPEN_CREATE.
262a0 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f ^If the mode o
262b0 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 ption is.**
262c0 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 set to "memory"
262d0 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d then a pure [in-
262e0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d memory database]
262f0 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 that never read
26300 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 s.** or writ
26310 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 es from disk is
26320 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 used. ^It is an
26330 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 error to specify
26340 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 a value for.**
26350 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 the mode par
26360 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c ameter that is l
26370 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 ess restrictive
26380 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 than that specif
26390 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 ied by.** th
263a0 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 e flags passed i
263b0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 n the third para
263c0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
263d0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a _open_v2()..**.*
263e0 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 * <li> <b>cach
263f0 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 e</b>: ^The cach
26400 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 e parameter may
26410 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 be set to either
26420 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 "shared" or.**
26430 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e "private". ^
26440 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 Setting it to "s
26450 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 hared" is equiva
26460 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 lent to setting
26470 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 the.** SQLIT
26480 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
26490 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c HE bit in the fl
264a0 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 ags argument pas
264b0 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 sed to.** sq
264c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
264d0 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 ^Setting the ca
264e0 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f che parameter to
264f0 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a "private" is .*
26500 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 * equivalent
26510 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 to setting the
26520 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
26530 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a ATECACHE bit..**
26540 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 ^If sqlite3
26550 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 _open_v2() is us
26560 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 ed and the "cach
26570 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 e" parameter is
26580 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 present in.**
26590 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 a URI filename
265a0 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 , its value over
265b0 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 rides any behavi
265c0 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 or requested by
265d0 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 setting.** S
265e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
265f0 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 TECACHE or SQLIT
26600 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
26610 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 HE flag..**.**
26620 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e <li> <b>psow</b>
26630 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 : ^The psow para
26640 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 meter indicates
26650 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
26660 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 he.** [power
26670 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 safe overwrite]
26680 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 property does or
26690 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 does not apply
266a0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 to the.** st
266b0 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 orage media on w
266c0 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73 hich the databas
266d0 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a e file resides..
266e0 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e **.** <li> <b>n
266f0 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 olock</b>: ^The
26700 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 nolock parameter
26710 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 is a boolean qu
26720 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ery parameter.**
26730 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65 which if se
26740 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 t disables file
26750 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 locking in rollb
26760 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 ack journal mode
26770 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 s. This.**
26780 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 is useful for ac
26790 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 cessing a databa
267a0 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 se on a filesyst
267b0 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 em that does not
267c0 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 .** support
267d0 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f locking. Cautio
267e0 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 n: Database cor
267f0 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 ruption might re
26800 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 sult if two.**
26810 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 or more proce
26820 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 sses write to th
26830 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
26840 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 and any one of t
26850 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 hose.** proc
26860 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 esses uses noloc
26870 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e k=1..**.** <li>
26880 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 <b>immutable</b
26890 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c >: ^The immutabl
268a0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 e parameter is a
268b0 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a boolean query.*
268c0 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 * parameter
268d0 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 that indicates t
268e0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 hat the database
268f0 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 file is stored
26900 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f on.** read-o
26910 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 nly media. ^Whe
26920 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 n immutable is s
26930 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d et, SQLite assum
26940 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 es that the.**
26950 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 database file
26960 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 cannot be chang
26970 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 ed, even by a pr
26980 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65 ocess with highe
26990 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 r.** privile
269a0 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 ge, and so the d
269b0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
269c0 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 d read-only and
269d0 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 all locking.**
269e0 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 and change de
269f0 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 tection is disab
26a00 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 led. Caution: S
26a10 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 etting the immut
26a20 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 able.** prop
26a30 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 erty on a databa
26a40 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 se file that doe
26a50 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 s in fact change
26a60 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 can result.**
26a70 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 in incorrect
26a80 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e query results an
26a90 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 d/or [SQLITE_COR
26aa0 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a RUPT] errors..**
26ab0 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b See also: [
26ac0 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d SQLITE_IOCAP_IMM
26ad0 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 UTABLE]..**
26ae0 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a .** </ul>.**.*
26af0 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e * ^Specifying an
26b00 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 unknown paramet
26b10 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 er in the query
26b20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 component of a U
26b30 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 RI is not an.**
26b40 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 error. Future v
26b50 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
26b60 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 e might understa
26b70 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 nd additional qu
26b80 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ery.** parameter
26b90 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 s. See "[query
26ba0 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 parameters with
26bb0 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 special meaning
26bc0 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a to SQLite]" for.
26bd0 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e ** additional in
26be0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
26bf0 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 [[URI filename
26c00 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 examples]] <h3>U
26c10 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d RI filename exam
26c20 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 ples</h3>.**.**
26c30 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 <table border="1
26c40 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 " align=center c
26c50 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a ellpadding=5>.**
26c60 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 <tr><th> URI fi
26c70 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 lenames <th> Res
26c80 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ults.** <tr><td>
26c90 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 file:data.db <t
26ca0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
26cb0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 Open the file "d
26cc0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 ata.db" in the c
26cd0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 urrent directory
26ce0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 ..** <tr><td> fi
26cf0 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 le:/home/fred/da
26d00 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 ta.db<br>.**
26d10 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f file:///ho
26d20 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 me/fred/data.db
26d30 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 <br> .**
26d40 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f file://localho
26d50 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 st/home/fred/dat
26d60 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a a.db <br> <td> .
26d70 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e ** Open
26d80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
26d90 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 le "/home/fred/d
26da0 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e ata.db"..** <tr>
26db0 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b <td> file://dark
26dc0 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 star/home/fred/d
26dd0 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 ata.db <td> .**
26de0 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f An erro
26df0 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 r. "darkstar" is
26e00 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 not a recognize
26e10 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 d authority..**
26e20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 <tr><td style="w
26e30 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 hite-space:nowra
26e40 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 p"> .**
26e50 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 file:///C:/Docu
26e60 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 ments%20and%20Se
26e70 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b ttings/fred/Desk
26e80 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 top/data.db.**
26e90 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 <td> Windows
26ea0 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 only: Open the f
26eb0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e ile "data.db" on
26ec0 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 fred's desktop
26ed0 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 on drive.**
26ee0 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 C:. Note th
26ef0 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 at the %20 escap
26f00 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d ing in this exam
26f10 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 ple is not stric
26f20 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 tly .**
26f30 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 necessary - spa
26f40 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 ce characters ca
26f50 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 n be used litera
26f60 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 lly.**
26f70 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 in URI filenames
26f80 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 ..** <tr><td> fi
26f90 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d le:data.db?mode=
26fa0 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 ro&cache=private
26fb0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
26fc0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 Open file "da
26fd0 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 ta.db" in the cu
26fe0 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 rrent directory
26ff0 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 for read-only ac
27000 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 cess..**
27010 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 Regardless of
27020 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 whether or not s
27030 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 hared-cache mode
27040 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a is enabled by.*
27050 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 * defau
27060 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 lt, use a privat
27070 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e e cache..** <tr>
27080 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f <td> file:/home/
27090 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 fred/data.db?vfs
270a0 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 =unix-dotfile <t
270b0 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f d>.** O
270c0 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f pen file "/home/
270d0 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 fred/data.db". U
270e0 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 se the special V
270f0 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 FS "unix-dotfile
27100 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 ".** th
27110 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 at uses dot-file
27120 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f s in place of po
27130 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 six advisory loc
27140 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 king..** <tr><td
27150 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d > file:data.db?m
27160 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 ode=readonly <td
27170 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 > .** A
27180 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e n error. "readon
27190 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c ly" is not a val
271a0 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 id option for th
271b0 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 e "mode" paramet
271c0 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a er..** </table>.
271d0 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 **.** ^URI hexad
271e0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 ecimal escape se
271f0 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 quences (%HH) ar
27200 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 e supported with
27210 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a in the path and.
27220 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 ** query compone
27230 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 nts of a URI. A
27240 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 hexadecimal esca
27250 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 pe sequence cons
27260 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 ists of a.** per
27270 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 cent sign - "%"
27280 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 - followed by ex
27290 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 actly two hexade
272a0 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a cimal digits .**
272b0 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f specifying an o
272c0 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 ctet value. ^Bef
272d0 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 ore the path or
272e0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 query components
272f0 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c of a.** URI fil
27300 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 ename are interp
27310 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 reted, they are
27320 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 encoded using UT
27330 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 F-8 and all .**
27340 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 hexadecimal esca
27350 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 pe sequences rep
27360 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c laced by a singl
27370 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e e byte containin
27380 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 g the.** corresp
27390 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 onding octet. If
273a0 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 this process ge
273b0 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c nerates an inval
273c0 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e id UTF-8 encodin
273d0 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 g,.** the result
273e0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
273f0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 .**.** <b>Note t
27400 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a o Windows users:
27410 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 </b> The encodi
27420 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 ng used for the
27430 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
27440 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f t.** of sqlite3_
27450 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
27460 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 e3_open_v2() mus
27470 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 t be UTF-8, not
27480 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 whatever.** code
27490 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c page is currentl
274a0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 y defined. File
274b0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 names containing
274c0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a international.*
274d0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 * characters mus
274e0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 t be converted t
274f0 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f o UTF-8 prior to
27500 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e passing them in
27510 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 to.** sqlite3_op
27520 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f en() or sqlite3_
27530 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a open_v2()..**.**
27540 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 <b>Note to Wind
27550 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 ows Runtime user
27560 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 s:</b> The temp
27570 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 orary directory
27580 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 must be set.** p
27590 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 rior to calling
275a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f sqlite3_open() o
275b0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
275c0 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 2(). Otherwise,
275d0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 various.** feat
275e0 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 ures that requir
275f0 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d e the use of tem
27600 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 porary files may
27610 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 fail..**.** See
27620 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
27630 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a temp_directory].
27640 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f */.int sqlite3_o
27650 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 pen(. const cha
27660 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f r *filename, /
27670 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e * Database filen
27680 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 ame (UTF-8) */.
27690 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 sqlite3 **ppDb
276a0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
276b0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
276c0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 e */.);.int sqli
276d0 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f te3_open16(. co
276e0 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 nst void *filena
276f0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
27700 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
27710 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 16) */. sqlite3
27720 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 **ppDb
27730 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
27740 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a db handle */.);.
27750 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e int sqlite3_open
27760 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 _v2(. const cha
27770 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f r *filename, /
27780 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e * Database filen
27790 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 ame (UTF-8) */.
277a0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c sqlite3 **ppDb,
277b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
277c0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
277d0 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 e */. int flags
277e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
277f0 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e * Flags */. con
27800 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 st char *zVfs
27810 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
27820 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 VFS module to us
27830 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e */.);../*.** C
27840 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 API3REF: Obtain
27850 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 Values For URI P
27860 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 arameters.**.**
27870 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 These are utilit
27880 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 y routines, usef
27890 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d ul to VFS implem
278a0 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 entations, that
278b0 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 check.** to see
278c0 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 if a database fi
278d0 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 le was a URI tha
278e0 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 t contained a sp
278f0 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a ecific query .**
27900 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 parameter, and
27910 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 if so obtains th
27920 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 e value of that
27930 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e query parameter.
27940 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 .**.** If F is t
27950 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
27960 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 name pointer pas
27970 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 sed into the xOp
27980 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a en() method of .
27990 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 ** a VFS impleme
279a0 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 ntation when the
279b0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
279c0 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 to xOpen() has
279d0 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 one or .** more
279e0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f of the [SQLITE_O
279f0 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c PEN_URI] or [SQL
27a00 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
27a10 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a ] bits set and.*
27a20 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 * P is the name
27a30 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 of the query par
27a40 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 ameter, then.**
27a50 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 sqlite3_uri_para
27a60 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 meter(F,P) retur
27a70 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 ns the value of
27a80 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 the P.** paramet
27a90 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 er if it exists
27aa0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 or a NULL pointe
27ab0 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 r if P does not
27ac0 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 appear as a .**
27ad0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 query parameter
27ae0 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 on F. If P is a
27af0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
27b00 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 of F.** has no
27b10 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 explicit value,
27b20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 then sqlite3_uri
27b30 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 _parameter(F,P)
27b40 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 returns.** a poi
27b50 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 nter to an empty
27b60 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 string..**.** T
27b70 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 he sqlite3_uri_b
27b80 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f oolean(F,P,B) ro
27b90 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 utine assumes th
27ba0 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 at P is a boolea
27bb0 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 n.** parameter a
27bc0 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 nd returns true
27bd0 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 (1) or false (0)
27be0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 according to th
27bf0 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e e value.** of P.
27c00 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 The sqlite3_ur
27c10 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 i_boolean(F,P,B)
27c20 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
27c30 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 true (1) if the
27c40 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 .** value of que
27c50 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 ry parameter P i
27c60 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 s one of "yes",
27c70 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 "true", or "on"
27c80 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f in any.** case o
27c90 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 r if the value b
27ca0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e egins with a non
27cb0 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 -zero number. T
27cc0 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 he .** sqlite3_u
27cd0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
27ce0 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 ) routines retur
27cf0 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 ns false (0) if
27d00 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 the value of.**
27d10 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 query parameter
27d20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 P is one of "no"
27d30 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f , "false", or "o
27d40 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 ff" in any case
27d50 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c or.** if the val
27d60 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 ue begins with a
27d70 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 numeric zero.
27d80 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 If P is not a qu
27d90 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ery.** parameter
27da0 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 on F or if the
27db0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f value of P is do
27dc0 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 es not match any
27dd0 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 of the.** above
27de0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 , then sqlite3_u
27df0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
27e00 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 ) returns (B!=0)
27e10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
27e20 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c te3_uri_int64(F,
27e30 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e P,D) routine con
27e40 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 verts the value
27e50 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 of P into a.** 6
27e60 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 4-bit signed int
27e70 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 eger and returns
27e80 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f that integer, o
27e90 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f r D if P does no
27ea0 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 t.** exist. If
27eb0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 the value of P i
27ec0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 s something othe
27ed0 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 r than an intege
27ee0 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 r, then.** zero
27ef0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
27f00 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 .** If F is a NU
27f10 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e LL pointer, then
27f20 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 sqlite3_uri_par
27f30 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 ameter(F,P) retu
27f40 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 rns NULL and.**
27f50 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c sqlite3_uri_bool
27f60 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 ean(F,P,B) retur
27f70 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e ns B. If F is n
27f80 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ot a NULL pointe
27f90 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 r and.** is not
27fa0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 a database file
27fb0 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 pathname pointer
27fc0 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 that SQLite pas
27fd0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 sed into the xOp
27fe0 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 en.** VFS method
27ff0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
28000 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 ior of this rout
28010 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ine is undefined
28020 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a and probably.**
28030 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f undesirable..*/
28040 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
28050 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 ite3_uri_paramet
28060 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a er(const char *z
28070 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 Filename, const
28080 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 char *zParam);.i
28090 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 nt sqlite3_uri_b
280a0 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 oolean(const cha
280b0 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 r *zFile, const
280c0 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e char *zParam, in
280d0 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c t bDefault);.sql
280e0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
280f0 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e e3_uri_int64(con
28100 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 st char*, const
28110 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 char*, sqlite3_i
28120 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 nt64);.../*.** C
28130 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 API3REF: Error C
28140 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 odes And Message
28150 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
28160 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ite3.**.** ^If t
28170 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 he most recent s
28180 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c qlite3_* API cal
28190 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 l associated wit
281a0 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 h .** [database
281b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 connection] D fa
281c0 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 iled, then the s
281d0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 qlite3_errcode(D
281e0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 ) interface.** r
281f0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 eturns the numer
28200 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d ic [result code]
28210 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 or [extended re
28220 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 sult code] for t
28230 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e hat.** API call.
28240 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 .** If the most
28250 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 recent API call
28260 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a was successful,.
28270 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 ** then the retu
28280 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 rn value from sq
28290 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 lite3_errcode()
282a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
282b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
282c0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 tended_errcode()
282d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
282e0 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 the same except
282f0 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 that it always
28300 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 returns the .**
28310 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
28320 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e code] even when
28330 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
28340 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 codes are.** di
28350 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 sabled..**.** ^T
28360 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 he sqlite3_errms
28370 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f g() and sqlite3_
28380 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 errmsg16() retur
28390 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 n English-langua
283a0 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 ge.** text that
283b0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 describes the er
283c0 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 ror, as either U
283d0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 TF-8 or UTF-16 r
283e0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
283f0 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 ^(Memory to hold
28400 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
28410 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e ge string is man
28420 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e aged internally.
28430 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
28440 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 ion does not nee
28450 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 d to worry about
28460 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 freeing the res
28470 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c ult..** However,
28480 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e the error strin
28490 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 g might be overw
284a0 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f ritten or deallo
284b0 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 cated by.** subs
284c0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
284d0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
284e0 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 erface functions
284f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 .)^.**.** ^The s
28500 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 qlite3_errstr()
28510 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
28520 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 s the English-la
28530 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 nguage text.** t
28540 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 hat describes th
28550 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c e [result code],
28560 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 as UTF-8..** ^(
28570 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 Memory to hold t
28580 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
28590 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 string is manag
285a0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a ed internally.**
285b0 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 and must not be
285c0 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 freed by the ap
285d0 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a plication)^..**.
285e0 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 ** When the seri
285f0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
28600 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 g mode] is in us
28610 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 e, it might be t
28620 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 he.** case that
28630 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f a second error o
28640 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 ccurs on a separ
28650 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 ate thread in be
28660 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d tween.** the tim
28670 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 e of the first e
28680 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c rror and the cal
28690 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 l to these inter
286a0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 faces..** When t
286b0 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 hat happens, the
286c0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 second error wi
286d0 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 ll be reported s
286e0 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e ince these.** in
286f0 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 terfaces always
28700 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 report the most
28710 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 recent result.
28720 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 To avoid.** this
28730 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 , each thread ca
28740 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 n obtain exclusi
28750 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 ve use of the [d
28760 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
28770 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f on] D.** by invo
28780 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 king [sqlite3_mu
28790 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 tex_enter]([sqli
287a0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 te3_db_mutex](D)
287b0 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 ) before beginni
287c0 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 ng.** to use D a
287d0 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c nd invoking [sql
287e0 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 ite3_mutex_leave
287f0 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 ]([sqlite3_db_mu
28800 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a tex](D)) after.*
28810 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 * all calls to t
28820 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 he interfaces li
28830 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f sted here are co
28840 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 mpleted..**.** I
28850 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 f an interface f
28860 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 ails with SQLITE
28870 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 _MISUSE, that me
28880 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 ans the interfac
28890 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 e.** was invoked
288a0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 incorrectly by
288b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e the application.
288c0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 In that case,
288d0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 the.** error cod
288e0 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 e and message ma
288f0 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 y or may not be
28900 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 set..*/.int sqli
28910 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 te3_errcode(sqli
28920 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 te3 *db);.int sq
28930 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 lite3_extended_e
28940 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a rrcode(sqlite3 *
28950 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 db);.const char
28960 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 *sqlite3_errmsg(
28970 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 sqlite3*);.const
28980 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 void *sqlite3_e
28990 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a rrmsg16(sqlite3*
289a0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
289b0 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e qlite3_errstr(in
289c0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
289d0 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 REF: Prepared St
289e0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a atement Object.*
289f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 * KEYWORDS: {pre
28a00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d pared statement}
28a10 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
28a20 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 ments}.**.** An
28a30 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
28a40 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e object represen
28a50 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 ts a single SQL
28a60 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a statement that.*
28a70 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 * has been compi
28a80 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 led into binary
28a90 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 form and is read
28aa0 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 y to be evaluate
28ab0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f d..**.** Think o
28ac0 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 f each SQL state
28ad0 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 ment as a separa
28ae0 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 te computer prog
28af0 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 ram. The.** ori
28b00 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 ginal SQL text i
28b10 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 s source code.
28b20 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 A prepared state
28b30 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 ment object .**
28b40 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 is the compiled
28b50 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c object code. Al
28b60 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f l SQL must be co
28b70 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a nverted into a.*
28b80 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 * prepared state
28b90 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 ment before it c
28ba0 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a an be run..**.**
28bb0 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 The life-cycle
28bc0 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 of a prepared st
28bd0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 atement object u
28be0 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 sually goes like
28bf0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c this:.**.** <ol
28c00 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 >.** <li> Create
28c10 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
28c20 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 atement object u
28c30 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 sing [sqlite3_pr
28c40 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 epare_v2()]..**
28c50 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 <li> Bind values
28c60 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d to [parameters]
28c70 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 using the sqlit
28c80 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 e3_bind_*().**
28c90 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a interfaces..
28ca0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 ** <li> Run the
28cb0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b SQL by calling [
28cc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
28cd0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 one or more time
28ce0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 s..** <li> Reset
28cf0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
28d00 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 atement using [s
28d10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
28d20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 then go back.**
28d30 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 to step 2.
28d40 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 Do this zero or
28d50 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 more times..**
28d60 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 <li> Destroy the
28d70 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 object using [s
28d80 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
28d90 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a )]..** </ol>.*/.
28da0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
28db0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 qlite3_stmt sqli
28dc0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a te3_stmt;../*.**
28dd0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 CAPI3REF: Run-t
28de0 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 ime Limits.** ME
28df0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
28e00 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 .** ^(This inter
28e10 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 face allows the
28e20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 size of various
28e30 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 constructs to be
28e40 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 limited.** on a
28e50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 connection by c
28e60 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e onnection basis.
28e70 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 The first para
28e80 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 meter is the.**
28e90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
28ea0 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 tion] whose limi
28eb0 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f t is to be set o
28ec0 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a r queried. The.
28ed0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 ** second parame
28ee0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 ter is one of th
28ef0 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 e [limit categor
28f00 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 ies] that define
28f10 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 a.** class of c
28f20 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 onstructs to be
28f30 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 size limited. T
28f40 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
28f50 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 er is the.** new
28f60 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 limit for that
28f70 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a construct.)^.**.
28f80 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c ** ^If the new l
28f90 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 imit is a negati
28fa0 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c ve number, the l
28fb0 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 imit is unchange
28fc0 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 d..** ^(For each
28fd0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 limit category
28fe0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e SQLITE_LIMIT_<i>
28ff0 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 NAME</i> there i
29000 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 s a .** [limits
29010 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 | hard upper bou
29020 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f nd].** set at co
29030 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 mpile-time by a
29040 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
29050 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b acro called.** [
29060 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f limits | SQLITE_
29070 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d MAX_<i>NAME</i>]
29080 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 ..** (The "_LIMI
29090 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 T_" in the name
290a0 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f is changed to "_
290b0 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 MAX_".))^.** ^At
290c0 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 tempts to increa
290d0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 se a limit above
290e0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 its hard upper
290f0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c bound are.** sil
29100 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 ently truncated
29110 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 to the hard uppe
29120 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e r bound..**.** ^
29130 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 Regardless of wh
29140 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
29150 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 limit was chang
29160 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c ed, the .** [sql
29170 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e ite3_limit()] in
29180 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
29190 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 the prior value
291a0 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a of the limit..**
291b0 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 ^Hence, to find
291c0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c the current val
291d0 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 ue of a limit wi
291e0 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 thout changing i
291f0 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 t,.** simply inv
29200 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 oke this interfa
29210 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 ce with the thir
29220 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 d parameter set
29230 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e to -1..**.** Run
29240 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 -time limits are
29250 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
29260 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e e in application
29270 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a s that manage.**
29280 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 both their own
29290 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 internal databas
292a0 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 e and also datab
292b0 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f ases that are co
292c0 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 ntrolled.** by u
292d0 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 ntrusted externa
292e0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 l sources. An e
292f0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 xample applicati
29300 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a on might be a.**
29310 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 web browser tha
29320 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 t has its own da
29330 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 tabases for stor
29340 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a ing history and.
29350 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 ** separate data
29360 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 bases controlled
29370 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 by JavaScript a
29380 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e pplications down
29390 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 loaded.** off th
293a0 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 e Internet. The
293b0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 internal databa
293c0 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e ses can be given
293d0 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 the.** large, d
293e0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 efault limits.
293f0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 Databases manage
29400 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f d by external so
29410 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 urces can.** be
29420 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c given much small
29430 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e er limits design
29440 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 ed to prevent a
29450 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 denial of servic
29460 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 e.** attack. De
29470 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 velopers might a
29480 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 lso want to use
29490 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 the [sqlite3_set
294a0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a _authorizer()].*
294b0 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 * interface to f
294c0 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 urther control u
294d0 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 ntrusted SQL. T
294e0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 he size of the d
294f0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 atabase.** creat
29500 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 ed by an untrust
29510 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 ed script can be
29520 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 contained using
29530 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 the.** [max_pag
29540 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 e_count] [PRAGMA
29550 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e ]..**.** New run
29560 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 -time limit cate
29570 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 gories may be ad
29580 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
29590 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 leases..*/.int s
295a0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c qlite3_limit(sql
295b0 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 ite3*, int id, i
295c0 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a nt newVal);../*.
295d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
295e0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 -Time Limit Cate
295f0 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 gories.** KEYWOR
29600 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 DS: {limit categ
29610 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 ory} {*limit cat
29620 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 egories}.**.** T
29630 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 hese constants d
29640 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 efine various pe
29650 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 rformance limits
29660 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 .** that can be
29670 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 lowered at run-t
29680 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ime using [sqlit
29690 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 e3_limit()]..**
296a0 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 The synopsis of
296b0 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 the meanings of
296c0 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 the various limi
296d0 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f ts is shown belo
296e0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c w..** Additional
296f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
29700 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 available at [li
29710 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e mits | Limits in
29720 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 SQLite]..**.**
29730 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 <dl>.** [[SQLITE
29740 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 _LIMIT_LENGTH]]
29750 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
29760 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a IT_LENGTH</dt>.*
29770 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
29780 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 m size of any st
29790 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 ring or BLOB or
297a0 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 table row, in by
297b0 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a tes.<dd>)^.**.**
297c0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
297d0 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c SQL_LENGTH]] ^(<
297e0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
297f0 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a SQL_LENGTH</dt>.
29800 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
29810 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 um length of an
29820 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 SQL statement, i
29830 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a n bytes.</dd>)^.
29840 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
29850 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 IMIT_COLUMN]] ^(
29860 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
29870 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 _COLUMN</dt>.**
29880 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
29890 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
298a0 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 s in a table def
298b0 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 inition or in th
298c0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 e.** result set
298d0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 of a [SELECT] or
298e0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d the maximum num
298f0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
29900 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 n an index.** or
29910 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 in an ORDER BY
29920 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 or GROUP BY clau
29930 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a se.</dd>)^.**.**
29940 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
29950 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c EXPR_DEPTH]] ^(<
29960 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
29970 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a EXPR_DEPTH</dt>.
29980 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
29990 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 um depth of the
299a0 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e parse tree on an
299b0 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 y expression.</d
299c0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
299d0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
299e0 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 ND_SELECT]] ^(<d
299f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 t>SQLITE_LIMIT_C
29a00 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f OMPOUND_SELECT</
29a10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
29a20 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
29a30 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 terms in a comp
29a40 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 ound SELECT stat
29a50 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ement.</dd>)^.**
29a60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
29a70 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c IT_VDBE_OP]] ^(<
29a80 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
29a90 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 VDBE_OP</dt>.**
29aa0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
29ab0 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 number of instru
29ac0 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 ctions in a virt
29ad0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 ual machine prog
29ae0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 ram.** used to i
29af0 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 mplement an SQL
29b00 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b statement. If [
29b10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
29b20 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 v2()] or.** the
29b30 65 71 75 69 76 61 6c 65 6e 74 20 74 72 69 65 73 equivalent tries
29b40 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 to allocate spa
29b50 63 65 20 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e ce for more than
29b60 20 74 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 this many opcod
29b70 65 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c es.** in a singl
29b80 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
29b90 6d 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f ment, an SQLITE_
29ba0 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73 20 72 NOMEM error is r
29bb0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a eturned.</dd>)^.
29bc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
29bd0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
29be0 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 G]] ^(<dt>SQLITE
29bf0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
29c00 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ARG</dt>.** <dd>
29c10 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
29c20 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
29c30 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f on a function.</
29c40 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
29c50 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 LITE_LIMIT_ATTAC
29c60 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 HED]] ^(<dt>SQLI
29c70 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 TE_LIMIT_ATTACHE
29c80 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
29c90 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
29ca0 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 of [ATTACH | at
29cb0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 tached databases
29cc0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ].)^</dd>.**.**
29cd0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c [[SQLITE_LIMIT_L
29ce0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
29cf0 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 TH]].** ^(<dt>SQ
29d00 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f LITE_LIMIT_LIKE_
29d10 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f PATTERN_LENGTH</
29d20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
29d30 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
29d40 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 the pattern arg
29d50 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 ument to the [LI
29d60 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d KE] or.** [GLOB]
29d70 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e operators.</dd>
29d80 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
29d90 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
29da0 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c _NUMBER]].** ^(<
29db0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
29dc0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c VARIABLE_NUMBER<
29dd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
29de0 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 maximum index nu
29df0 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 mber of any [par
29e00 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 ameter] in an SQ
29e10 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a L statement.)^.*
29e20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
29e30 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 MIT_TRIGGER_DEPT
29e40 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 H]] ^(<dt>SQLITE
29e50 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 _LIMIT_TRIGGER_D
29e60 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 EPTH</dt>.** <dd
29e70 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 >The maximum dep
29e80 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 th of recursion
29e90 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 for triggers.</d
29ea0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
29eb0 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 ITE_LIMIT_WORKER
29ec0 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 _THREADS]] ^(<dt
29ed0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f >SQLITE_LIMIT_WO
29ee0 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 RKER_THREADS</dt
29ef0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
29f00 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 imum number of a
29f10 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 uxiliary worker
29f20 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73 threads that a s
29f30 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 ingle.** [prepar
29f40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 ed statement] ma
29f50 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a y start.</dd>)^.
29f60 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
29f70 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
29f80 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 _LENGTH
29f90 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 0.#de
29fa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
29fb0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 T_SQL_LENGTH
29fc0 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 1.#d
29fd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
29fe0 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 IT_COLUMN
29ff0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 2.#
2a000 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
2a010 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 MIT_EXPR_DEPTH
2a020 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 3.
2a030 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
2a040 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
2a050 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 LECT 4
2a060 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2a070 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 LIMIT_VDBE_OP
2a080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2a090 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
2a0a0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
2a0b0 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 ARG
2a0c0 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 6.#define SQLIT
2a0d0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 E_LIMIT_ATTACHED
2a0e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2a0f0 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 7.#define SQLI
2a100 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 TE_LIMIT_LIKE_PA
2a110 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 TTERN_LENGTH
2a120 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 8.#define SQL
2a130 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
2a140 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 LE_NUMBER
2a150 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 9.#define SQ
2a160 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
2a170 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 ER_DEPTH
2a180 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 10.#define S
2a190 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b QLITE_LIMIT_WORK
2a1a0 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 ER_THREADS
2a1b0 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 11../*.** C
2a1c0 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 API3REF: Prepare
2a1d0 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 Flags.**.** The
2a1e0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 se constants def
2a1f0 69 6e 65 20 76 61 72 69 6f 75 73 20 66 6c 61 67 ine various flag
2a200 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 61 s that can be pa
2a210 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72 ssed into.** "pr
2a220 65 70 46 6c 61 67 73 22 20 70 61 72 61 6d 65 74 epFlags" paramet
2a230 65 72 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 er of the [sqlit
2a240 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d e3_prepare_v3()]
2a250 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
2a260 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d _prepare16_v3()]
2a270 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a interfaces..**.
2a280 2a 2a 20 4e 65 77 20 66 6c 61 67 73 20 6d 61 79 ** New flags may
2a290 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
2a2a0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
2a2b0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 SQLite..**.** <d
2a2c0 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 l>.** [[SQLITE_P
2a2d0 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e REPARE_PERSISTEN
2a2e0 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 T]] ^(<dt>SQLITE
2a2f0 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 _PREPARE_PERSIST
2a300 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ENT</dt>.** <dd>
2a310 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 The SQLITE_PREPA
2a320 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 66 6c RE_PERSISTENT fl
2a330 61 67 20 69 73 20 61 20 68 69 6e 74 20 74 6f 20 ag is a hint to
2a340 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 the query planne
2a350 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 r.** that the pr
2a360 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2a370 20 77 69 6c 6c 20 62 65 20 72 65 74 61 69 6e 65 will be retaine
2a380 64 20 66 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d d for a long tim
2a390 65 20 61 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c e and.** probabl
2a3a0 79 20 72 65 75 73 65 64 20 6d 61 6e 79 20 74 69 y reused many ti
2a3b0 6d 65 73 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20 mes.)^ ^Without
2a3c0 74 68 69 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69 this flag, [sqli
2a3d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 te3_prepare_v3()
2a3e0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
2a3f0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 3_prepare16_v3()
2a400 5d 20 61 73 73 75 6d 65 20 74 68 61 74 20 74 68 ] assume that th
2a410 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
2a420 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65 ment will .** be
2a430 20 75 73 65 64 20 6a 75 73 74 20 6f 6e 63 65 20 used just once
2a440 6f 72 20 61 74 20 6d 6f 73 74 20 61 20 66 65 77 or at most a few
2a450 20 74 69 6d 65 73 20 61 6e 64 20 74 68 65 6e 20 times and then
2a460 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a destroyed using.
2a470 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ** [sqlite3_fina
2a480 6c 69 7a 65 28 29 5d 20 72 65 6c 61 74 69 76 65 lize()] relative
2a490 6c 79 20 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72 ly soon. The cur
2a4a0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 rent implementat
2a4b0 69 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74 ion acts.** on t
2a4c0 68 69 73 20 68 69 6e 74 20 62 79 20 61 76 6f 69 his hint by avoi
2a4d0 64 69 6e 67 20 74 68 65 20 75 73 65 20 6f 66 20 ding the use of
2a4e0 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 [lookaside memor
2a4f0 79 5d 20 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a y] so as not to.
2a500 2a 2a 20 64 65 70 6c 65 74 65 20 74 68 65 20 6c ** deplete the l
2a510 69 6d 69 74 65 64 20 73 74 6f 72 65 20 6f 66 20 imited store of
2a520 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
2a530 2e 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e . Future version
2a540 73 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d s of.** SQLite m
2a550 61 79 20 61 63 74 20 6f 6e 20 74 68 69 73 20 68 ay act on this h
2a560 69 6e 74 20 64 69 66 66 65 72 65 6e 74 6c 79 2e int differently.
2a570 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 .** </dl>.*/.#de
2a580 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50 fine SQLITE_PREP
2a590 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 20 ARE_PERSISTENT
2a5a0 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 31 0x01
2a5b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2a5c0 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 : Compiling An S
2a5d0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 QL Statement.**
2a5e0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 KEYWORDS: {SQL s
2a5f0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 tatement compile
2a600 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 r}.** METHOD: sq
2a610 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 lite3.** CONSTRU
2a620 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 CTOR: sqlite3_st
2a630 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 mt.**.** To exec
2a640 75 74 65 20 61 6e 20 53 51 4c 20 73 74 61 74 65 ute an SQL state
2a650 6d 65 6e 74 2c 20 69 74 20 6d 75 73 74 20 66 69 ment, it must fi
2a660 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 rst be compiled
2a670 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 into a byte-code
2a680 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e .** program usin
2a690 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 g one of these r
2a6a0 6f 75 74 69 6e 65 73 2e 20 20 4f 72 2c 20 69 6e outines. Or, in
2a6b0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
2a6c0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ese routines.**
2a6d0 61 72 65 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 are constructors
2a6e0 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 for the [prepar
2a6f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 ed statement] ob
2a700 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ject..**.** The
2a710 70 72 65 66 65 72 72 65 64 20 72 6f 75 74 69 6e preferred routin
2a720 65 20 74 6f 20 75 73 65 20 69 73 20 5b 73 71 6c e to use is [sql
2a730 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2a740 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c )]. The.** [sql
2a750 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
2a760 69 6e 74 65 72 66 61 63 65 20 69 73 20 6c 65 67 interface is leg
2a770 61 63 79 20 61 6e 64 20 73 68 6f 75 6c 64 20 62 acy and should b
2a780 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73 e avoided..** [s
2a790 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2a7a0 33 28 29 5d 20 68 61 73 20 61 6e 20 65 78 74 72 3()] has an extr
2a7b0 61 20 22 70 72 65 70 46 6c 61 67 73 22 20 6f 70 a "prepFlags" op
2a7c0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73 65 tion that is use
2a7d0 64 0a 2a 2a 20 66 6f 72 20 73 70 65 63 69 61 6c d.** for special
2a7e0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a purposes..**.**
2a7f0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 The use of the
2a800 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 73 UTF-8 interfaces
2a810 20 69 73 20 70 72 65 66 65 72 72 65 64 2c 20 61 is preferred, a
2a820 73 20 53 51 4c 69 74 65 20 63 75 72 72 65 6e 74 s SQLite current
2a830 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c 20 70 ly.** does all p
2a840 61 72 73 69 6e 67 20 75 73 69 6e 67 20 55 54 46 arsing using UTF
2a850 2d 38 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20 -8. The UTF-16
2a860 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 interfaces are p
2a870 72 6f 76 69 64 65 64 0a 2a 2a 20 61 73 20 61 20 rovided.** as a
2a880 63 6f 6e 76 65 6e 69 65 6e 63 65 2e 20 20 54 68 convenience. Th
2a890 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61 e UTF-16 interfa
2a8a0 63 65 73 20 77 6f 72 6b 20 62 79 20 63 6f 6e 76 ces work by conv
2a8b0 65 72 74 69 6e 67 20 74 68 65 0a 2a 2a 20 69 6e erting the.** in
2a8c0 70 75 74 20 74 65 78 74 20 69 6e 74 6f 20 55 54 put text into UT
2a8d0 46 2d 38 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 69 F-8, then invoki
2a8e0 6e 67 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e ng the correspon
2a8f0 64 69 6e 67 20 55 54 46 2d 38 20 69 6e 74 65 72 ding UTF-8 inter
2a900 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 face..**.** The
2a910 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 first argument,
2a920 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 "db", is a [data
2a930 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2a940 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 obtained from a
2a950 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 .** prior succes
2a960 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
2a970 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
2a980 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
2a990 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
2a9a0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 3_open16()]. Th
2a9b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
2a9c0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 ction must not h
2a9d0 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e ave been closed.
2a9e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e .**.** The secon
2a9f0 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 d argument, "zSq
2aa00 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 l", is the state
2aa10 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 ment to be compi
2aa20 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 led, encoded.**
2aa30 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 as either UTF-8
2aa40 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 or UTF-16. The
2aa50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
2aa60 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 ), sqlite3_prepa
2aa70 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 re_v2(),.** and
2aa80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2aa90 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 v3().** interfac
2aaa0 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e es use UTF-8, an
2aab0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
2aac0 65 31 36 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 e16(), sqlite3_p
2aad0 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a repare16_v2(),.*
2aae0 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 * and sqlite3_pr
2aaf0 65 70 61 72 65 31 36 5f 76 33 28 29 20 75 73 65 epare16_v3() use
2ab00 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e UTF-16..**.** ^
2ab10 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 If the nByte arg
2ab20 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 ument is negativ
2ab30 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 e, then zSql is
2ab40 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a read up to the.*
2ab50 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 * first zero ter
2ab60 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 minator. ^If nBy
2ab70 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 te is positive,
2ab80 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a then it is the.*
2ab90 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 * number of byte
2aba0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c s read from zSql
2abb0 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 . ^If nByte is
2abc0 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 zero, then no pr
2abd0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d epared.** statem
2abe0 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 ent is generated
2abf0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c ..** If the call
2ac00 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 er knows that th
2ac10 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e e supplied strin
2ac20 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 g is nul-termina
2ac30 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 ted, then.** the
2ac40 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 re is a small pe
2ac50 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 rformance advant
2ac60 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 age to passing a
2ac70 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 n nByte paramete
2ac80 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 r that.** is the
2ac90 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2aca0 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 in the input st
2acb0 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e ring <i>includin
2acc0 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c g</i>.** the nul
2acd0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a -terminator..**.
2ace0 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 ** ^If pzTail is
2acf0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a not NULL then *
2ad00 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 pzTail is made t
2ad10 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 o point to the f
2ad20 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 irst byte.** pas
2ad30 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 t the end of the
2ad40 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 first SQL state
2ad50 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 ment in zSql. T
2ad60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e hese routines on
2ad70 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 ly.** compile th
2ad80 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e e first statemen
2ad90 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 t in zSql, so *p
2ada0 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f zTail is left po
2adb0 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 inting to.** wha
2adc0 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 t remains uncomp
2add0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 iled..**.** ^*pp
2ade0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 Stmt is left poi
2adf0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 nting to a compi
2ae00 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 led [prepared st
2ae10 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 atement] that ca
2ae20 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 n be.** executed
2ae30 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
2ae40 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 step()]. ^If th
2ae50 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c ere is an error,
2ae60 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a *ppStmt is set.
2ae70 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 ** to NULL. ^If
2ae80 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 the input text
2ae90 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 contains no SQL
2aea0 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 (if the input is
2aeb0 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 an empty.** str
2aec0 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 ing or a comment
2aed0 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 ) then *ppStmt i
2aee0 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a s set to NULL..*
2aef0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 * The calling pr
2af00 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f ocedure is respo
2af10 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 nsible for delet
2af20 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 ing the compiled
2af30 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
2af40 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
2af50 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 _finalize()] aft
2af60 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 er it has finish
2af70 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 ed with it..** p
2af80 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 pStmt may not be
2af90 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e NULL..**.** ^On
2afa0 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 success, the sq
2afb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 lite3_prepare()
2afc0 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e family of routin
2afd0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 es return [SQLIT
2afe0 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 E_OK];.** otherw
2aff0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f ise an [error co
2b000 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
2b010 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
2b020 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c e3_prepare_v2(),
2b030 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
2b040 5f 76 33 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 _v3(), sqlite3_p
2b050 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a repare16_v2(),.*
2b060 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 * and sqlite3_pr
2b070 65 70 61 72 65 31 36 5f 76 33 28 29 20 69 6e 74 epare16_v3() int
2b080 65 72 66 61 63 65 73 20 61 72 65 20 72 65 63 6f erfaces are reco
2b090 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 mmended for all
2b0a0 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a new programs..**
2b0b0 20 54 68 65 20 6f 6c 64 65 72 20 69 6e 74 65 72 The older inter
2b0c0 66 61 63 65 73 20 28 73 71 6c 69 74 65 33 5f 70 faces (sqlite3_p
2b0d0 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c repare() and sql
2b0e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
2b0f0 29 0a 2a 2a 20 61 72 65 20 72 65 74 61 69 6e 65 ).** are retaine
2b100 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 d for backwards
2b110 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 compatibility, b
2b120 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 ut their use is
2b130 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 discouraged..**
2b140 5e 49 6e 20 74 68 65 20 22 76 58 22 20 69 6e 74 ^In the "vX" int
2b150 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 erfaces, the pre
2b160 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a pared statement.
2b170 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 ** that is retur
2b180 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 ned (the [sqlite
2b190 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 3_stmt] object)
2b1a0 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 contains a copy
2b1b0 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e of the.** origin
2b1c0 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 al SQL text. Thi
2b1d0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 s causes the [sq
2b1e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e lite3_step()] in
2b1f0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 terface to.** be
2b200 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 have differently
2b210 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a in three ways:.
2b220 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c **.** <ol>.** <l
2b230 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 i>.** ^If the da
2b240 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 tabase schema ch
2b250 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f anges, instead o
2b260 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c f returning [SQL
2b270 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 ITE_SCHEMA] as i
2b280 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 t.** always used
2b290 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 to do, [sqlite3
2b2a0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 _step()] will au
2b2b0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f tomatically reco
2b2c0 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a mpile the SQL.**
2b2d0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
2b2e0 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 ry to run it aga
2b2f0 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b in. As many as [
2b300 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d SQLITE_MAX_SCHEM
2b310 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 A_RETRY].** retr
2b320 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 ies will occur b
2b330 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 efore sqlite3_st
2b340 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e ep() gives up an
2b350 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 d returns an err
2b360 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a or..** </li>.**.
2b370 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e ** <li>.** ^When
2b380 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
2b390 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
2b3a0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f )] will return o
2b3b0 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c ne of the detail
2b3c0 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 ed.** [error cod
2b3d0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 es] or [extended
2b3e0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 error codes].
2b3f0 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 ^The legacy beha
2b400 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a vior was that.**
2b410 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2b420 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 ] would only ret
2b430 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 urn a generic [S
2b440 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 QLITE_ERROR] res
2b450 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 ult code.** and
2b460 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
2b470 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 would have to ma
2b480 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c ke a second call
2b490 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
2b4a0 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 et()].** in orde
2b4b0 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e r to find the un
2b4c0 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f derlying cause o
2b4d0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 f the problem. W
2b4e0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 ith the "v2" pre
2b4f0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 pare.** interfac
2b500 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 es, the underlyi
2b510 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 ng reason for th
2b520 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 e error is retur
2b530 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e ned immediately.
2b540 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 .** </li>.**.**
2b550 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 <li>.** ^If the
2b560 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 specific value b
2b570 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 ound to [paramet
2b580 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 er | host parame
2b590 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 ter] in the .**
2b5a0 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 WHERE clause mig
2b5b0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 ht influence the
2b5c0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 choice of query
2b5d0 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 plan for a stat
2b5e0 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 ement,.** then t
2b5f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c he statement wil
2b600 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c l be automatical
2b610 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 ly recompiled, a
2b620 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 s if there had b
2b630 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 een .** a schema
2b640 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 change, on the
2b650 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f first [sqlite3_
2b660 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c step()] call fol
2b670 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 lowing any chang
2b680 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c e.** to the [sql
2b690 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c ite3_bind_text |
2b6a0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 bindings] of th
2b6b0 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 at [parameter].
2b6c0 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 .** ^The specifi
2b6d0 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 c value of WHERE
2b6e0 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 -clause [paramet
2b6f0 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 er] might influe
2b700 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 nce the .** choi
2b710 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e ce of query plan
2b720 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
2b730 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 r is the left-ha
2b740 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 nd side of a [LI
2b750 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d KE].** or [GLOB]
2b760 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 operator or if
2b770 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 the parameter is
2b780 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 compared to an
2b790 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a indexed column.*
2b7a0 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 * and the [SQLIT
2b7b0 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 E_ENABLE_STAT3]
2b7c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
2b7d0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a ion is enabled..
2b7e0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c ** </li>.**.** <
2b7f0 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72 65 70 61 p>^sqlite3_prepa
2b800 72 65 5f 76 33 28 29 20 64 69 66 66 65 72 73 20 re_v3() differs
2b810 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72 65 from sqlite3_pre
2b820 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69 pare_v2() only i
2b830 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20 n having.** the
2b840 65 78 74 72 61 20 70 72 65 70 46 6c 61 67 73 20 extra prepFlags
2b850 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68 parameter, which
2b860 20 69 73 20 61 20 62 69 74 20 61 72 72 61 79 20 is a bit array
2b870 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a 65 consisting of ze
2b880 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 ro or.** more of
2b890 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 50 52 45 the [SQLITE_PRE
2b8a0 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 7c PARE_PERSISTENT|
2b8b0 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 2a SQLITE_PREPARE_*
2b8c0 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a ] flags. ^The.*
2b8d0 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 * sqlite3_prepar
2b8e0 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 e_v2() interface
2b8f0 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 74 works exactly t
2b900 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 he same as.** sq
2b910 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 lite3_prepare_v3
2b920 28 29 20 77 69 74 68 20 61 20 7a 65 72 6f 20 70 () with a zero p
2b930 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74 repFlags paramet
2b940 65 72 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a er..** </ol>.*/.
2b950 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
2b960 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a are(. sqlite3 *
2b970 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
2b980 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
2b990 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
2b9a0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
2b9b0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
2b9c0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
2b9d0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
2b9e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
2b9f0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
2ba00 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
2ba10 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
2ba20 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
2ba30 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
2ba40 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
2ba50 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
2ba60 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
2ba70 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
2ba80 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
2ba90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
2baa0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c repare_v2(. sql
2bab0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
2bac0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
2bad0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
2bae0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
2baf0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
2bb00 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 ement, UTF-8 enc
2bb10 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
2bb20 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
2bb30 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
2bb40 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
2bb50 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
2bb60 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
2bb70 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
2bb80 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
2bb90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a const char **pz
2bba0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
2bbb0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
2bbc0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
2bbd0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c ql */.);.int sql
2bbe0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 ite3_prepare_v3(
2bbf0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
2bc00 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
2bc10 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f tabase handle */
2bc20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
2bc30 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 Sql, /* SQ
2bc40 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 L statement, UTF
2bc50 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 -8 encoded */.
2bc60 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
2bc70 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
2bc80 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
2bc90 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
2bca0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 unsigned int pr
2bcb0 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f epFlags, /* Zero
2bcc0 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f or more SQLITE_
2bcd0 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a PREPARE_ flags *
2bce0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
2bcf0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
2bd00 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
2bd10 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
2bd20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 char **pzTail
2bd30 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
2bd40 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
2bd50 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
2bd60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 ;.int sqlite3_pr
2bd70 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 epare16(. sqlit
2bd80 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
2bd90 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
2bda0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
2bdb0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 void *zSql,
2bdc0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
2bdd0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f ent, UTF-16 enco
2bde0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
2bdf0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
2be00 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
2be10 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
2be20 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
2be30 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
2be40 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
2be50 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
2be60 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 const void **pzT
2be70 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
2be80 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
2be90 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
2bea0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 l */.);.int sqli
2beb0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
2bec0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
2bed0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
2bee0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
2bef0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
2bf00 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
2bf10 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
2bf20 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a F-16 encoded */.
2bf30 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
2bf40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
2bf50 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
2bf60 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
2bf70 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
2bf80 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
2bf90 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
2bfa0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
2bfb0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 oid **pzTail
2bfc0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
2bfd0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
2bfe0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
2bff0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 .int sqlite3_pre
2c000 70 61 72 65 31 36 5f 76 33 28 0a 20 20 73 71 6c pare16_v3(. sql
2c010 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
2c020 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
2c030 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
2c040 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 st void *zSql,
2c050 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
2c060 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e ement, UTF-16 en
2c070 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
2c080 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
2c090 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
2c0a0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
2c0b0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 bytes. */. unsi
2c0c0 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61 gned int prepFla
2c0d0 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d gs, /* Zero or m
2c0e0 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 ore SQLITE_PREPA
2c0f0 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 RE_ flags */. s
2c100 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
2c110 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
2c120 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
2c130 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
2c140 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
2c150 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
2c160 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
2c170 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a f zSql */.);../*
2c180 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
2c190 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 trieving Stateme
2c1a0 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 nt SQL.** METHOD
2c1b0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
2c1c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2c1d0 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 3_sql(P) interfa
2c1e0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
2c1f0 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f nter to a copy o
2c200 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53 f the UTF-8.** S
2c210 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 QL text used to
2c220 63 72 65 61 74 65 20 5b 70 72 65 70 61 72 65 64 create [prepared
2c230 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66 statement] P if
2c240 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65 P was.** create
2c250 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 d by [sqlite3_pr
2c260 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 epare_v2()], [sq
2c270 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 lite3_prepare_v3
2c280 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
2c290 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
2c2a0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 , or [sqlite3_pr
2c2b0 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a epare16_v3()]..*
2c2c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
2c2d0 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 xpanded_sql(P) i
2c2e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
2c2f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
2c300 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 UTF-8.** string
2c310 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53 containing the S
2c320 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 QL text of prepa
2c330 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 red statement P
2c340 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 with.** [bound p
2c350 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e arameters] expan
2c360 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 ded..**.** ^(For
2c370 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 example, if a p
2c380 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2c390 74 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 t is created usi
2c3a0 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 ng the SQL.** te
2c3b0 78 74 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c xt "SELECT $abc,
2c3c0 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72 :xyz" and if par
2c3d0 61 6d 65 74 65 72 20 24 61 62 63 20 69 73 20 62 ameter $abc is b
2c3e0 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20 ound to integer
2c3f0 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 2345.** and para
2c400 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e meter :xyz is un
2c410 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 bound, then sqli
2c420 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 te3_sql() will r
2c430 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 eturn.** the ori
2c440 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 ginal string, "S
2c450 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 ELECT $abc,:xyz"
2c460 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70 but sqlite3_exp
2c470 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 anded_sql().** w
2c480 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45 ill return "SELE
2c490 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e CT 2345,NULL".)^
2c4a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2c4b0 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c te3_expanded_sql
2c4c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
2c4d0 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 urns NULL if ins
2c4e0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 ufficient memory
2c4f0 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65 .** is available
2c500 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 to hold the res
2c510 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72 ult, or if the r
2c520 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 esult would exce
2c530 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 ed the.** the ma
2c540 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e ximum string len
2c550 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62 gth determined b
2c560 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 y the [SQLITE_LI
2c570 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a MIT_LENGTH]..**.
2c580 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
2c590 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 TRACE_SIZE_LIMIT
2c5a0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
2c5b0 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 ption limits the
2c5c0 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e size of.** boun
2c5d0 64 20 70 61 72 61 6d 65 74 65 72 20 65 78 70 61 d parameter expa
2c5e0 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 nsions. ^The [S
2c5f0 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 QLITE_OMIT_TRACE
2c600 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a ] compile-time.*
2c610 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20 * option causes
2c620 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 sqlite3_expanded
2c630 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 _sql() to always
2c640 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a return NULL..**
2c650 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 .** ^The string
2c660 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
2c670 74 65 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61 te3_sql(P) is ma
2c680 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74 65 20 naged by SQLite
2c690 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 and is.** automa
2c6a0 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68 tically freed wh
2c6b0 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 20 en the prepared
2c6c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e statement is fin
2c6d0 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 alized..** ^The
2c6e0 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 string returned
2c6f0 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e by sqlite3_expan
2c700 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74 ded_sql(P), on t
2c710 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a he other hand,.*
2c720 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 * is obtained fr
2c730 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
2c740 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62 oc()] and must b
2c750 65 20 66 72 65 65 20 62 79 20 74 68 65 20 61 70 e free by the ap
2c760 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 plication.** by
2c770 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 passing it to [s
2c780 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
2c790 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
2c7a0 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 qlite3_sql(sqlit
2c7b0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
2c7c0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 .char *sqlite3_e
2c7d0 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69 xpanded_sql(sqli
2c7e0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2c7f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2c800 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
2c810 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
2c820 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 Writes The Data
2c830 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 base.** METHOD:
2c840 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
2c850 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2c860 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 stmt_readonly(X)
2c870 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2c880 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 ns true (non-zer
2c890 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c o) if.** and onl
2c8a0 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 y if the [prepar
2c8b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 ed statement] X
2c8c0 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 makes no direct
2c8d0 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 changes to.** th
2c8e0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
2c8f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a database file..
2c900 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
2c910 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
2c920 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
2c930 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 ns] or.** [virtu
2c940 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 al tables] might
2c950 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 change the data
2c960 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 base indirectly
2c970 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 as a side effect
2c980 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 . .** ^(For exa
2c990 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c mple, if an appl
2c9a0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 ication defines
2c9b0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c a function "eval
2c9c0 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c ()" that .** cal
2c9d0 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ls [sqlite3_exec
2c9e0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f ()], then the fo
2c9f0 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 llowing SQL stat
2ca00 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 ement would.** c
2ca10 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 hange the databa
2ca20 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 se file through
2ca30 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a side-effects:.**
2ca40 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
2ca50 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 <pre>.** SELE
2ca60 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 CT eval('DELETE
2ca70 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 FROM t1') FROM t
2ca80 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 2;.** </pre></bl
2ca90 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
2caa0 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 But because the
2cab0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
2cac0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e nt does not chan
2cad0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ge the database
2cae0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 file.** directly
2caf0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 , sqlite3_stmt_r
2cb00 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 eadonly() would
2cb10 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 still return tru
2cb20 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e e.)^.**.** ^Tran
2cb30 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 saction control
2cb40 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 statements such
2cb50 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d as [BEGIN], [COM
2cb60 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d MIT], [ROLLBACK]
2cb70 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d ,.** [SAVEPOINT]
2cb80 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 , and [RELEASE]
2cb90 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 cause sqlite3_st
2cba0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f mt_readonly() to
2cbb0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a return true,.**
2cbc0 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 since the state
2cbd0 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 ments themselves
2cbe0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 do not actually
2cbf0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 modify the data
2cc00 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 base but.** rath
2cc10 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 er they control
2cc20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 the timing of wh
2cc30 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 en other stateme
2cc40 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a nts modify the .
2cc50 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 ** database. ^T
2cc60 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 he [ATTACH] and
2cc70 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 [DETACH] stateme
2cc80 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a nts also cause.*
2cc90 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 * sqlite3_stmt_r
2cca0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 eadonly() to ret
2ccb0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 urn true since,
2ccc0 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 while those stat
2ccd0 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 ements.** change
2cce0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
2ccf0 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 on of a database
2cd00 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 connection, the
2cd10 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a y do not make .*
2cd20 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 * changes to the
2cd30 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
2cd40 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f database files o
2cd50 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 n disk..** ^The
2cd60 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 sqlite3_stmt_rea
2cd70 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63 donly() interfac
2cd80 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 66 e returns true f
2cd90 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65 or [BEGIN] since
2cda0 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65 .** [BEGIN] mere
2cdb0 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c ly sets internal
2cdc0 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20 flags, but the
2cdd0 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d [BEGIN|BEGIN IMM
2cde0 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b EDIATE] and.** [
2cdf0 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c BEGIN|BEGIN EXCL
2ce00 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 USIVE] commands
2ce10 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61 74 do touch the dat
2ce20 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 abase and so.**
2ce30 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 sqlite3_stmt_rea
2ce40 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20 donly() returns
2ce50 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20 false for those
2ce60 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 commands..*/.int
2ce70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
2ce80 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 adonly(sqlite3_s
2ce90 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
2cea0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
2ceb0 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 termine If A Pre
2cec0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 pared Statement
2ced0 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a Has Been Reset.*
2cee0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
2cef0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
2cf00 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 e sqlite3_stmt_b
2cf10 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 usy(S) interface
2cf20 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e returns true (n
2cf30 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a on-zero) if the.
2cf40 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
2cf50 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 tement] S has be
2cf60 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 en stepped at le
2cf70 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a ast once using .
2cf80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
2cf90 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69 (S)] but has nei
2cfa0 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 ther run to comp
2cfb0 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 letion (returned
2cfc0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 .** [SQLITE_DONE
2cfd0 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f ] from [sqlite3_
2cfe0 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a step(S)]) nor.**
2cff0 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e been reset usin
2d000 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
2d010 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 (S)]. ^The sqli
2d020 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 te3_stmt_busy(S)
2d030 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 .** interface re
2d040 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 turns false if S
2d050 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
2d060 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 er. If S is not
2d070 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e a .** NULL poin
2d080 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 ter and is not a
2d090 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 pointer to a va
2d0a0 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 lid [prepared st
2d0b0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 atement].** obje
2d0c0 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 ct, then the beh
2d0d0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
2d0e0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 ed and probably
2d0f0 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a undesirable..**.
2d100 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
2d110 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e e can be used in
2d120 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 combination [sq
2d130 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 lite3_next_stmt(
2d140 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 )].** to locate
2d150 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 all prepared sta
2d160 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 tements associat
2d170 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 ed with a databa
2d180 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f se .** connectio
2d190 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 n that are in ne
2d1a0 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 ed of being rese
2d1b0 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 t. This can be
2d1c0 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 used,.** for exa
2d1d0 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 mple, in diagnos
2d1e0 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 tic routines to
2d1f0 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 search for prepa
2d200 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e red .** statemen
2d210 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 ts that are hold
2d220 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f ing a transactio
2d230 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 n open..*/.int s
2d240 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 qlite3_stmt_busy
2d250 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
2d260 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2d270 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 : Dynamically Ty
2d280 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 ped Value Object
2d290 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 .** KEYWORDS: {p
2d2a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2d2b0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 _value} {unprote
2d2c0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2d2d0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ue}.**.** SQLite
2d2e0 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 uses the sqlite
2d2f0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 3_value object t
2d300 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 o represent all
2d310 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 values.** that c
2d320 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 an be stored in
2d330 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
2d340 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 . SQLite uses dy
2d350 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 namic typing.**
2d360 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 for the values i
2d370 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 t stores. ^Valu
2d380 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c es stored in sql
2d390 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
2d3a0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 ts.** can be int
2d3b0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 egers, floating
2d3c0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 point values, st
2d3d0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 rings, BLOBs, or
2d3e0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 NULL..**.** An
2d3f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2d400 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 ject may be eith
2d410 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f er "protected" o
2d420 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e r "unprotected".
2d430 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 .** Some interfa
2d440 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 ces require a pr
2d450 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2d460 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e value. Other in
2d470 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c terfaces.** will
2d480 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 accept either a
2d490 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e protected or an
2d4a0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c unprotected sql
2d4b0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 ite3_value..** E
2d4c0 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 very interface t
2d4d0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 hat accepts sqli
2d4e0 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 te3_value argume
2d4f0 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a nts specifies.**
2d500 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
2d510 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 it requires a pr
2d520 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2d530 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b value. The.** [
2d540 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 sqlite3_value_du
2d550 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 p()] interface c
2d560 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f an be used to co
2d570 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a nstruct a new .*
2d580 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 * protected sqli
2d590 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 te3_value from a
2d5a0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 n unprotected sq
2d5b0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a lite3_value..**.
2d5c0 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 ** The terms "pr
2d5d0 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e otected" and "un
2d5e0 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 protected" refer
2d5f0 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e to whether or n
2d600 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 ot.** a mutex is
2d610 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 held. An inter
2d620 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c nal mutex is hel
2d630 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 d for a protecte
2d640 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
2d650 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f ue object but no
2d660 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 mutex is held f
2d670 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 or an unprotecte
2d680 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
2d690 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 ue object. If S
2d6a0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
2d6b0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 d to be single-t
2d6c0 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 hreaded.** (with
2d6d0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
2d6e0 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 AFE=0] and with
2d6f0 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 [sqlite3_threads
2d700 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 afe()] returning
2d710 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 0).** or if SQL
2d720 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e ite is run in on
2d730 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 e of reduced mut
2d740 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 ex modes .** [SQ
2d750 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
2d760 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 LETHREAD] or [SQ
2d770 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
2d780 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e ITHREAD].** then
2d790 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 there is no dis
2d7a0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e tinction between
2d7b0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 protected and u
2d7c0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 nprotected.** sq
2d7d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
2d7e0 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e cts and they can
2d7f0 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 be used interch
2d800 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 angeably. Howev
2d810 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d er,.** for maxim
2d820 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c um code portabil
2d830 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d ity it is recomm
2d840 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 ended that appli
2d850 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c cations.** still
2d860 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e make the distin
2d870 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 ction between pr
2d880 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 otected and unpr
2d890 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
2d8a0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
2d8b0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 even when not s
2d8c0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 trictly required
2d8d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
2d8e0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
2d8f0 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 ts that are pass
2d900 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 ed as parameters
2d910 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 into the.** imp
2d920 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b lementation of [
2d930 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
2d940 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
2d950 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 s] are protected
2d960 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
2d970 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 3_value object r
2d980 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
2d990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
2d9a0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 lue()] is unprot
2d9b0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 ected..** Unprot
2d9c0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2d9d0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 lue objects may
2d9e0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 only be used wit
2d9f0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 h.** [sqlite3_re
2da00 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e sult_value()] an
2da10 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f d [sqlite3_bind_
2da20 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 value()]..** The
2da30 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2da40 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 blob | sqlite3_v
2da50 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d alue_type()] fam
2da60 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 ily of.** interf
2da70 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f aces require pro
2da80 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2da90 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f alue objects..*/
2daa0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
2dab0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71 sqlite3_value sq
2dac0 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a lite3_value;../*
2dad0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 .** CAPI3REF: SQ
2dae0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 L Function Conte
2daf0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 xt Object.**.**
2db00 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 The context in w
2db10 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 hich an SQL func
2db20 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 tion executes is
2db30 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a stored in an.**
2db40 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
2db50 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 object. ^A poi
2db60 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 nter to an sqlit
2db70 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 e3_context objec
2db80 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 t.** is always f
2db90 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
2dba0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 o [application-d
2dbb0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
2dbc0 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 ions]..** The ap
2dbd0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2dbe0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 d SQL function i
2dbf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
2dc00 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 ll pass this.**
2dc10 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 pointer through
2dc20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 into calls to [s
2dc30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
2dc40 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 t | sqlite3_resu
2dc50 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 lt()],.** [sqlit
2dc60 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
2dc70 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 text()], [sqlite
2dc80 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 3_user_data()],.
2dc90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ** [sqlite3_cont
2dca0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d ext_db_handle()]
2dcb0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 , [sqlite3_get_a
2dcc0 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e uxdata()],.** an
2dcd0 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 d/or [sqlite3_se
2dce0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f t_auxdata()]..*/
2dcf0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
2dd00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
2dd10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b sqlite3_context;
2dd20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2dd30 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 : Binding Values
2dd40 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 To Prepared Sta
2dd50 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f tements.** KEYWO
2dd60 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d RDS: {host param
2dd70 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 eter} {host para
2dd80 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 meters} {host pa
2dd90 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a rameter name}.**
2dda0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 KEYWORDS: {SQL
2ddb0 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 parameter} {SQL
2ddc0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 parameters} {par
2ddd0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a ameter binding}.
2dde0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
2ddf0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 e3_stmt.**.** ^(
2de00 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 In the SQL state
2de10 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 ment text input
2de20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 to [sqlite3_prep
2de30 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 are_v2()] and it
2de40 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c s variants,.** l
2de50 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 iterals may be r
2de60 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 eplaced by a [pa
2de70 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 rameter] that ma
2de80 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c tches one of fol
2de90 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 lowing.** templa
2dea0 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a tes:.**.** <ul>.
2deb0 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c ** <li> ?.** <l
2dec0 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e i> ?NNN.** <li>
2ded0 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 :VVV.** <li>
2dee0 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 @VVV.** <li> $V
2def0 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a VV.** </ul>.**.*
2df00 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 * In the templat
2df10 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 es above, NNN re
2df20 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 presents an inte
2df30 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 ger literal,.**
2df40 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e and VVV represen
2df50 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 ts an alphanumer
2df60 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e ic identifier.)^
2df70 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 ^The values of
2df80 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 these.** parame
2df90 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 ters (also calle
2dfa0 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 d "host paramete
2dfb0 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c r names" or "SQL
2dfc0 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a parameters").**
2dfd0 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e can be set usin
2dfe0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 g the sqlite3_bi
2dff0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
2e000 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a defined here..**
2e010 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
2e020 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 rgument to the s
2e030 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
2e040 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 routines is alwa
2e050 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 ys.** a pointer
2e060 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
2e070 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 stmt] object ret
2e080 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 urned from.** [s
2e090 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2e0a0 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 2()] or its vari
2e0b0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ants..**.** ^The
2e0c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
2e0d0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
2e0e0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 the SQL paramet
2e0f0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a er to be set..**
2e100 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 ^The leftmost S
2e110 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 QL parameter has
2e120 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 an index of 1.
2e130 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 ^When the same
2e140 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 named.** SQL par
2e150 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d ameter is used m
2e160 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 ore than once, s
2e170 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 econd and subseq
2e180 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e uent.** occurren
2e190 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d ces have the sam
2e1a0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 e index as the f
2e1b0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e irst occurrence.
2e1c0 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 .** ^The index f
2e1d0 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 or named paramet
2e1e0 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 ers can be looke
2e1f0 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a d up using the.*
2e200 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2e210 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
2e220 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 )] API if desire
2e230 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a d. ^The index.*
2e240 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 * for "?NNN" par
2e250 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 ameters is the v
2e260 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 alue of NNN..**
2e270 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d ^The NNN value m
2e280 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 ust be between 1
2e290 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 and the [sqlite
2e2a0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 3_limit()].** pa
2e2b0 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f rameter [SQLITE_
2e2c0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
2e2d0 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 UMBER] (default
2e2e0 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a value: 999)..**.
2e2f0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 ** ^The third ar
2e300 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 gument is the va
2e310 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 lue to bind to t
2e320 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a he parameter..**
2e330 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 ^If the third p
2e340 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
2e350 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 te3_bind_text()
2e360 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f or sqlite3_bind_
2e370 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 text16().** or s
2e380 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2e390 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 () is a NULL poi
2e3a0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f nter then the fo
2e3b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a urth parameter.*
2e3c0 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 * is ignored and
2e3d0 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 the end result
2e3e0 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 is the same as s
2e3f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c qlite3_bind_null
2e400 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 ()..**.** ^(In t
2e410 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 hose routines th
2e420 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 at have a fourth
2e430 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 argument, its v
2e440 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e alue is the.** n
2e450 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
2e460 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e n the parameter.
2e470 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 To be clear: t
2e480 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a he value is the.
2e490 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e ** number of <u>
2e4a0 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 bytes</u> in the
2e4b0 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 value, not the
2e4c0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
2e4d0 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 ters.)^.** ^If t
2e4e0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
2e4f0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ter to sqlite3_b
2e500 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 ind_text() or sq
2e510 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
2e520 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 6().** is negati
2e530 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e ve, then the len
2e540 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e gth of the strin
2e550 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 g is.** the numb
2e560 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 er of bytes up t
2e570 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f o the first zero
2e580 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 terminator..**
2e590 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
2e5a0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
2e5b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 e3_bind_blob() i
2e5c0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e s negative, then
2e5d0 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 .** the behavior
2e5e0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
2e5f0 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 * If a non-negat
2e600 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d ive fourth param
2e610 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 eter is provided
2e620 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
2e630 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 _text().** or sq
2e640 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
2e650 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 6() or sqlite3_b
2e660 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 ind_text64() the
2e670 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 n.** that parame
2e680 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 ter must be the
2e690 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 byte offset.** w
2e6a0 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 here the NUL ter
2e6b0 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 minator would oc
2e6c0 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 cur assuming the
2e6d0 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c string were NUL
2e6e0 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 .** terminated.
2e6f0 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 If any NUL char
2e700 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 acters occur at
2e710 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 byte offsets les
2e720 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 s than .** the v
2e730 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 alue of the four
2e740 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 th parameter the
2e750 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 n the resulting
2e760 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c string value wil
2e770 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 l.** contain emb
2e780 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 edded NULs. The
2e790 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 result of expre
2e7a0 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 ssions involving
2e7b0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 strings.** with
2e7c0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 embedded NULs i
2e7d0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
2e7e0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 ** ^The fifth ar
2e7f0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c gument to the BL
2e800 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 OB and string bi
2e810 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 nding interfaces
2e820 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 .** is a destruc
2e830 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 tor used to disp
2e840 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 ose of the BLOB
2e850 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 or.** string aft
2e860 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 er SQLite has fi
2e870 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 nished with it.
2e880 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 ^The destructor
2e890 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f is called.** to
2e8a0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 dispose of the
2e8b0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 BLOB or string e
2e8c0 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 ven if the call
2e8d0 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c to bind API fail
2e8e0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 s..** ^If the fi
2e8f0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a fth argument is.
2e900 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 ** the special v
2e910 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 alue [SQLITE_STA
2e920 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 TIC], then SQLit
2e930 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 e assumes that t
2e940 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f he.** informatio
2e950 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 n is in static,
2e960 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 unmanaged space
2e970 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 and does not nee
2e980 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a d to be freed..*
2e990 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 * ^If the fifth
2e9a0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 argument has the
2e9b0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 value [SQLITE_T
2e9c0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a RANSIENT], then.
2e9d0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ** SQLite makes
2e9e0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
2e9f0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 copy of the data
2ea00 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 immediately, be
2ea10 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 fore.** the sqli
2ea20 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
2ea30 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a tine returns..**
2ea40 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 .** ^The sixth a
2ea50 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
2ea60 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 e3_bind_text64()
2ea70 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a must be one of.
2ea80 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d ** [SQLITE_UTF8]
2ea90 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d , [SQLITE_UTF16]
2eaa0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 , [SQLITE_UTF16B
2eab0 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 E], or [SQLITE_U
2eac0 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 TF16LE].** to sp
2ead0 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 ecify the encodi
2eae0 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 ng of the text i
2eaf0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 n the third para
2eb00 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 meter. If.** th
2eb10 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 e sixth argument
2eb20 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
2eb30 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 _text64() is not
2eb40 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 one of the.** a
2eb50 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 llowed values sh
2eb60 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 own above, or if
2eb70 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 the text encodi
2eb80 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a ng is different.
2eb90 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f ** from the enco
2eba0 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 ding specified b
2ebb0 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61 y the sixth para
2ebc0 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 meter, then the
2ebd0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 behavior.** is u
2ebe0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
2ebf0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e ^The sqlite3_bin
2ec00 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 d_zeroblob() rou
2ec10 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f tine binds a BLO
2ec20 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 B of length N th
2ec30 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 at.** is filled
2ec40 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 with zeroes. ^A
2ec50 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 zeroblob uses a
2ec60 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 fixed amount of
2ec70 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 memory.** (just
2ec80 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 an integer to h
2ec90 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 old its size) wh
2eca0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 ile it is being
2ecb0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 processed..** Ze
2ecc0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 roblobs are inte
2ecd0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 nded to serve as
2ece0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f placeholders fo
2ecf0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a r BLOBs whose.**
2ed00 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 content is late
2ed10 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a r written using.
2ed20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ** [sqlite3_blob
2ed30 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e _open | incremen
2ed40 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f tal BLOB I/O] ro
2ed50 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 utines..** ^A ne
2ed60 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 gative value for
2ed70 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 the zeroblob re
2ed80 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d sults in a zero-
2ed90 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a length BLOB..**.
2eda0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2edb0 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49 bind_pointer(S,I
2edc0 2c 50 2c 54 2c 44 29 20 72 6f 75 74 69 6e 65 20 ,P,T,D) routine
2edd0 63 61 75 73 65 73 20 74 68 65 20 49 2d 74 68 20 causes the I-th
2ede0 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 parameter in.**
2edf0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2ee00 65 6e 74 5d 20 53 20 74 6f 20 68 61 76 65 20 61 ent] S to have a
2ee10 6e 20 53 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e n SQL value of N
2ee20 55 4c 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f ULL, but to also
2ee30 20 62 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 be.** associate
2ee40 64 20 77 69 74 68 20 74 68 65 20 70 6f 69 6e 74 d with the point
2ee50 65 72 20 50 20 6f 66 20 74 79 70 65 20 54 2e 20 er P of type T.
2ee60 20 5e 44 20 69 73 20 65 69 74 68 65 72 20 61 20 ^D is either a
2ee70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 0a NULL pointer or.
2ee80 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
2ee90 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e a destructor fun
2eea0 63 74 69 6f 6e 20 66 6f 72 20 50 2e 20 5e 53 51 ction for P. ^SQ
2eeb0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 Lite will invoke
2eec0 20 74 68 65 0a 2a 2a 20 64 65 73 74 72 75 63 74 the.** destruct
2eed0 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 or D with a sing
2eee0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 50 le argument of P
2eef0 20 77 68 65 6e 20 69 74 20 69 73 20 66 69 6e 69 when it is fini
2ef00 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 50 2e shed using.** P.
2ef10 20 20 54 68 65 20 54 20 70 61 72 61 6d 65 74 65 The T paramete
2ef20 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 73 74 r should be a st
2ef30 61 74 69 63 20 73 74 72 69 6e 67 2c 20 70 72 65 atic string, pre
2ef40 66 65 72 61 62 6c 79 20 61 20 73 74 72 69 6e 67 ferably a string
2ef50 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 20 54 68 65 .** literal. The
2ef60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f sqlite3_bind_po
2ef70 69 6e 74 65 72 28 29 20 72 6f 75 74 69 6e 65 20 inter() routine
2ef80 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a is part of the.*
2ef90 2a 20 5b 70 6f 69 6e 74 65 72 20 70 61 73 73 69 * [pointer passi
2efa0 6e 67 20 69 6e 74 65 72 66 61 63 65 5d 20 61 64 ng interface] ad
2efb0 64 65 64 20 66 6f 72 20 53 51 4c 69 74 65 20 33 ded for SQLite 3
2efc0 2e 32 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 .20.0..**.** ^If
2efd0 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 any of the sqli
2efe0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
2eff0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
2f000 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 with a NULL poi
2f010 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 nter.** for the
2f020 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2f030 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 ent] or with a p
2f040 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2f050 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b t for which.** [
2f060 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2f070 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 has been called
2f080 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 more recently th
2f090 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 an [sqlite3_rese
2f0a0 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 t()],.** then th
2f0b0 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 e call will retu
2f0c0 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 rn [SQLITE_MISUS
2f0d0 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 E]. If any sqli
2f0e0 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 te3_bind_().** r
2f0f0 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 outine is passed
2f100 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2f110 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 tement] that has
2f120 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c been finalized,
2f130 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 the.** result i
2f140 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
2f150 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c probably harmful
2f160 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 ..**.** ^Binding
2f170 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 s are not cleare
2f180 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
2f190 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 3_reset()] routi
2f1a0 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 ne..** ^Unbound
2f1b0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 parameters are i
2f1c0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 nterpreted as NU
2f1d0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 LL..**.** ^The s
2f1e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f qlite3_bind_* ro
2f1f0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 utines return [S
2f200 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
2f210 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 cess or an.** [e
2f220 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e rror code] if an
2f230 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e ything goes wron
2f240 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 g..** ^[SQLITE_T
2f250 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 OOBIG] might be
2f260 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 returned if the
2f270 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 size of a string
2f280 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 or BLOB.** exce
2f290 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 eds limits impos
2f2a0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c ed by [sqlite3_l
2f2b0 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 imit]([SQLITE_LI
2f2c0 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a MIT_LENGTH]) or.
2f2d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c ** [SQLITE_MAX_L
2f2e0 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c ENGTH]..** ^[SQL
2f2f0 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 ITE_RANGE] is re
2f300 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 turned if the pa
2f310 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 rameter.** index
2f320 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
2f330 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 . ^[SQLITE_NOME
2f340 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 M] is returned i
2f350 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 f malloc() fails
2f360 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
2f370 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
2f380 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
2f390 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
2f3a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
2f3b0 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c ame()], and [sql
2f3c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2f3d0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
2f3e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
2f3f0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 d_blob(sqlite3_s
2f400 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
2f410 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 void*, int n, v
2f420 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
2f430 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
2f440 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f _blob64(sqlite3_
2f450 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
2f460 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 t void*, sqlite3
2f470 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 _uint64,.
2f480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2f490 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
2f4a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
2f4b0 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 nd_double(sqlite
2f4c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 3_stmt*, int, do
2f4d0 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 uble);.int sqlit
2f4e0 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 e3_bind_int(sqli
2f4f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2f500 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 int);.int sqlite
2f510 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 3_bind_int64(sql
2f520 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
2f530 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b sqlite3_int64);
2f540 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
2f550 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 d_null(sqlite3_s
2f560 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 tmt*, int);.int
2f570 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2f580 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
2f590 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c int,const char*,
2f5a0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 int,void(*)(void
2f5b0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 *));.int sqlite3
2f5c0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c _bind_text16(sql
2f5d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
2f5e0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
2f5f0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
2f600 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f ));.int sqlite3_
2f610 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 bind_text64(sqli
2f620 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2f630 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c const char*, sql
2f640 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 ite3_uint64,.
2f650 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2f660 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f void(*)(vo
2f670 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 id*), unsigned c
2f680 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 har encoding);.i
2f690 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2f6a0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 value(sqlite3_st
2f6b0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
2f6c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
2f6d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
2f6e0 64 5f 70 6f 69 6e 74 65 72 28 73 71 6c 69 74 65 d_pointer(sqlite
2f6f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f 3_stmt*, int, vo
2f700 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a id*, const char*
2f710 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 ,void(*)(void*))
2f720 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
2f730 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 nd_zeroblob(sqli
2f740 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2f750 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 int n);.int sqli
2f760 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f te3_bind_zeroblo
2f770 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 b64(sqlite3_stmt
2f780 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f *, int, sqlite3_
2f790 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 uint64);../*.**
2f7a0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
2f7b0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 Of SQL Paramete
2f7c0 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 rs.** METHOD: sq
2f7d0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
2f7e0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 ^This routine c
2f7f0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 an be used to fi
2f800 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 nd the number of
2f810 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 [SQL parameters
2f820 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 ].** in a [prepa
2f830 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 red statement].
2f840 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 SQL parameters
2f850 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 are tokens of th
2f860 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 e.** form "?", "
2f870 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 ?NNN", ":AAA", "
2f880 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 $AAA", or "@AAA"
2f890 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a that serve as.*
2f8a0 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 * placeholders f
2f8b0 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 or values that a
2f8c0 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 re [sqlite3_bind
2f8d0 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a _blob | bound].*
2f8e0 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 * to the paramet
2f8f0 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 ers at a later t
2f900 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 ime..**.** ^(Thi
2f910 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c s routine actual
2f920 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 ly returns the i
2f930 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 ndex of the larg
2f940 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a est (rightmost).
2f950 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f ** parameter. Fo
2f960 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 r all forms exce
2f970 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 pt ?NNN, this wi
2f980 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f ll correspond to
2f990 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
2f9a0 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 f unique paramet
2f9b0 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 ers. If paramet
2f9c0 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 ers of the ?NNN
2f9d0 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a form are used,.*
2f9e0 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 * there may be g
2f9f0 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e aps in the list.
2fa00 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 )^.**.** See als
2fa10 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
2fa20 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
2fa30 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nd()],.** [sqlit
2fa40 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2fa50 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a r_name()], and.*
2fa60 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2fa70 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
2fa80 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 )]..*/.int sqlit
2fa90 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2faa0 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f r_count(sqlite3_
2fab0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
2fac0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 API3REF: Name Of
2fad0 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 A Host Paramete
2fae0 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c r.** METHOD: sql
2faf0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
2fb00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e ^The sqlite3_bin
2fb10 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
2fb20 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 (P,N) interface
2fb30 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e returns.** the n
2fb40 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 ame of the N-th
2fb50 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 [SQL parameter]
2fb60 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 in the [prepared
2fb70 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a statement] P..*
2fb80 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 * ^(SQL paramete
2fb90 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 rs of the form "
2fba0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 ?NNN" or ":AAA"
2fbb0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 or "@AAA" or "$A
2fbc0 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 AA".** have a na
2fbd0 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 me which is the
2fbe0 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 string "?NNN" or
2fbf0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 ":AAA" or "@AAA
2fc00 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 " or "$AAA".** r
2fc10 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
2fc20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
2fc30 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 the initial ":"
2fc40 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 or "$" or "@" or
2fc50 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 "?".** is inclu
2fc60 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 ded as part of t
2fc70 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 he name.)^.** ^P
2fc80 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
2fc90 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 form "?" withou
2fca0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e t a following in
2fcb0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 teger have no na
2fcc0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 me.** and are re
2fcd0 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 ferred to as "na
2fce0 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e meless" or "anon
2fcf0 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 ymous parameters
2fd00 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 "..**.** ^The fi
2fd10 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 rst host paramet
2fd20 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 er has an index
2fd30 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a of 1, not 0..**.
2fd40 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 ** ^If the value
2fd50 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e N is out of ran
2fd60 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 ge or if the N-t
2fd70 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a h parameter is.*
2fd80 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e * nameless, then
2fd90 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 NULL is returne
2fda0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 d. ^The returne
2fdb0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 d string is.** a
2fdc0 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 lways in UTF-8 e
2fdd0 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 ncoding even if
2fde0 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 the named parame
2fdf0 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 ter was.** origi
2fe00 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 nally specified
2fe10 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 as UTF-16 in [sq
2fe20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
2fe30 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
2fe40 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c prepare16_v2()],
2fe50 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
2fe60 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a pare16_v3()]..**
2fe70 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
2fe80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2fe90 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
2fea0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
2feb0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
2fec0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 nt()], and.** [s
2fed0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2fee0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
2fef0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
2ff00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2ff10 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 meter_name(sqlit
2ff20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a e3_stmt*, int);.
2ff30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2ff40 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 Index Of A Para
2ff50 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 meter With A Giv
2ff60 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f en Name.** METHO
2ff70 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
2ff80 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 **.** ^Return th
2ff90 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 e index of an SQ
2ffa0 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 L parameter give
2ffb0 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 n its name. ^Th
2ffc0 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 e.** index value
2ffd0 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 returned is sui
2ffe0 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 table for use as
2fff0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 the second.** p
30000 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
30010 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
30020 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 qlite3_bind()].
30030 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 ^A zero.** is r
30040 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 eturned if no ma
30050 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 tching parameter
30060 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 is found. ^The
30070 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 parameter.** na
30080 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e me must be given
30090 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 in UTF-8 even i
300a0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 f the original s
300b0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 tatement.** was
300c0 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 prepared from UT
300d0 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 F-16 text using
300e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
300f0 31 36 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 16_v2()] or.** [
30100 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
30110 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 6_v3()]..**.** S
30120 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
30130 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
30140 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
30150 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
30160 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
30170 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
30180 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
30190 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 _name()]..*/.int
301a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 sqlite3_bind_pa
301b0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 rameter_index(sq
301c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e lite3_stmt*, con
301d0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b st char *zName);
301e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
301f0 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 : Reset All Bind
30200 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 ings On A Prepar
30210 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 ed Statement.**
30220 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
30230 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 stmt.**.** ^Cont
30240 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 rary to the intu
30250 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b ition of many, [
30260 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
30270 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a does not reset.
30280 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ** the [sqlite3_
30290 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 bind_blob | bind
302a0 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 ings] on a [prep
302b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
302c0 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f .** ^Use this ro
302d0 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 utine to reset a
302e0 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 ll host paramete
302f0 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 rs to NULL..*/.i
30300 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 nt sqlite3_clear
30310 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 _bindings(sqlite
30320 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
30330 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 CAPI3REF: Numbe
30340 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 r Of Columns In
30350 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 A Result Set.**
30360 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
30370 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 stmt.**.** ^Retu
30380 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 rn the number of
30390 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
303a0 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 result set retur
303b0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 ned by the.** [p
303c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
303d0 74 5d 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75 t]. ^If this rou
303e0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20 tine returns 0,
303f0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a that means the .
30400 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
30410 74 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 tement] returns
30420 6e 6f 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 no data (for exa
30430 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d mple an [UPDATE]
30440 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 )..** ^However,
30450 6a 75 73 74 20 62 65 63 61 75 73 65 20 74 68 69 just because thi
30460 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
30470 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d s a positive num
30480 62 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 ber does not.**
30490 6d 65 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 mean that one or
304a0 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61 more rows of da
304b0 74 61 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 ta will be retur
304c0 6e 65 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 ned. ^A SELECT
304d0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c statement.** wil
304e0 6c 20 61 6c 77 61 79 73 20 68 61 76 65 20 61 20 l always have a
304f0 70 6f 73 69 74 69 76 65 20 73 71 6c 69 74 65 33 positive sqlite3
30500 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 _column_count()
30510 62 75 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e but depending on
30520 20 74 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c the.** WHERE cl
30530 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 ause constraints
30540 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63 and the table c
30550 6f 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 ontent, it might
30560 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e return no rows.
30570 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
30580 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 [sqlite3_data_c
30590 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 ount()].*/.int s
305a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f qlite3_column_co
305b0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
305c0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
305d0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d CAPI3REF: Colum
305e0 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 n Names In A Res
305f0 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f ult Set.** METHO
30600 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
30610 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
30620 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 tines return the
30630 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 name assigned t
30640 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 o a particular c
30650 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 olumn.** in the
30660 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 result set of a
30670 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
30680 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 nt. ^The sqlite
30690 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 3_column_name().
306a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 ** interface ret
306b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
306c0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 o a zero-termina
306d0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 ted UTF-8 string
306e0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f .** and sqlite3_
306f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 column_name16()
30700 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
30710 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d r to a zero-term
30720 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 inated.** UTF-16
30730 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 string. ^The f
30740 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
30750 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 s the [prepared
30760 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 statement].** th
30770 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 at implements th
30780 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 e [SELECT] state
30790 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e ment. ^The secon
307a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
307b0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d he.** column num
307c0 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d ber. ^The leftm
307d0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 ost column is nu
307e0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 mber 0..**.** ^T
307f0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
30800 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 ng pointer is va
30810 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 lid until either
30820 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
30830 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 tatement].** is
30840 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 destroyed by [sq
30850 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
30860 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 ] or until the s
30870 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f tatement is auto
30880 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 matically.** rep
30890 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 repared by the f
308a0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 irst call to [sq
308b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f lite3_step()] fo
308c0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 r a particular r
308d0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 un.** or until t
308e0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a he next call to.
308f0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
30900 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 n_name() or sqli
30910 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
30920 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 6() on the same
30930 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 column..**.** ^I
30940 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 f sqlite3_malloc
30950 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 () fails during
30960 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f the processing o
30970 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 f either routine
30980 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 .** (for example
30990 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 during a conver
309a0 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 sion from UTF-8
309b0 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 to UTF-16) then
309c0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
309d0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a r is returned..*
309e0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f *.** ^The name o
309f0 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d f a result colum
30a00 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f n is the value o
30a10 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 f the "AS" claus
30a20 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f e for.** that co
30a30 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 lumn, if there i
30a40 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 s an AS clause.
30a50 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 If there is no
30a60 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 AS clause.** the
30a70 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
30a80 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 e column is unsp
30a90 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 ecified and may
30aa0 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f change from.** o
30ab0 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 ne release of SQ
30ac0 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 Lite to the next
30ad0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 ..*/.const char
30ae0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
30af0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
30b00 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 t*, int N);.cons
30b10 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
30b20 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 column_name16(sq
30b30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
30b40 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 N);../*.** CAPI
30b50 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 3REF: Source Of
30b60 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 Data In A Query
30b70 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 Result.** METHOD
30b80 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
30b90 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
30ba0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d ines provide a m
30bb0 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e eans to determin
30bc0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 e the database,
30bd0 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 table, and.** ta
30be0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 ble column that
30bf0 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 is the origin of
30c00 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 a particular re
30c10 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a sult column in.*
30c20 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 * [SELECT] state
30c30 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 ment..** ^The na
30c40 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
30c50 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 se or table or c
30c60 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 olumn can be ret
30c70 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 urned as.** eith
30c80 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 er a UTF-8 or UT
30c90 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 F-16 string. ^T
30ca0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f he _database_ ro
30cb0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a utines return.**
30cc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 the database na
30cd0 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 me, the _table_
30ce0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
30cf0 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 the table name,
30d00 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 and.** the origi
30d10 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 n_ routines retu
30d20 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 rn the column na
30d30 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 me..** ^The retu
30d40 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 rned string is v
30d50 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b alid until the [
30d60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
30d70 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 nt] is destroyed
30d80 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 .** using [sqlit
30d90 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
30da0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 r until the stat
30db0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 ement is automat
30dc0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 ically.** reprep
30dd0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 ared by the firs
30de0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
30df0 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 e3_step()] for a
30e00 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a particular run.
30e10 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 ** or until the
30e20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e same information
30e30 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a is requested.**
30e40 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 again in a diff
30e50 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a erent encoding..
30e60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 **.** ^The names
30e70 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 returned are th
30e80 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c e original un-al
30e90 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 iased names of t
30ea0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 he.** database,
30eb0 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d table, and colum
30ec0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 n..**.** ^The fi
30ed0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
30ee0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
30ef0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 is a [prepared
30f00 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e statement]..** ^
30f10 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
30f20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 return informati
30f30 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 on about the Nth
30f40 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 result column r
30f50 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 eturned by.** th
30f60 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 e statement, whe
30f70 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f re N is the seco
30f80 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 nd function argu
30f90 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 ment..** ^The le
30fa0 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 ft-most column i
30fb0 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 s column 0 for t
30fc0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a hese routines..*
30fd0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 *.** ^If the Nth
30fe0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 column returned
30ff0 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e by the statemen
31000 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 t is an expressi
31010 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 on or.** subquer
31020 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 y and is not a c
31030 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 olumn value, the
31040 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 n all of these f
31050 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a unctions return.
31060 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 ** NULL. ^These
31070 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 routine might a
31080 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 lso return NULL
31090 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f if a memory allo
310a0 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 cation error.**
310b0 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 occurs. ^Otherw
310c0 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e ise, they return
310d0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
310e0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 attached databa
310f0 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 se, table,.** or
31100 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 column that que
31110 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e ry result column
31120 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 was extracted f
31130 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 rom..**.** ^As w
31140 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 ith all other SQ
31150 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 Lite APIs, those
31160 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 whose names end
31170 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 with "16" retur
31180 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f n.** UTF-16 enco
31190 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 ded strings and
311a0 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 the other functi
311b0 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 ons return UTF-8
311c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 ..**.** ^These A
311d0 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 PIs are only ava
311e0 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 ilable if the li
311f0 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c brary was compil
31200 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ed with the.** [
31210 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f SQLITE_ENABLE_CO
31220 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 LUMN_METADATA] C
31230 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 -preprocessor sy
31240 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 mbol..**.** If t
31250 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 wo or more threa
31260 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d ds call one or m
31270 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 ore of these rou
31280 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 tines against th
31290 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 e same.** prepar
312a0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 ed statement and
312b0 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 column at the s
312c0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 ame time then th
312d0 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a e results are.**
312e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
312f0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 * If two or more
31300 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e threads call on
31310 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 e or more.** [sq
31320 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 lite3_column_dat
31330 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c abase_name | col
31340 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 umn metadata int
31350 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 erfaces].** for
31360 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 the same [prepar
31370 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e ed statement] an
31380 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a d result column.
31390 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 ** at the same t
313a0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 ime then the res
313b0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
313c0 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 ed..*/.const cha
313d0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
313e0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 n_database_name(
313f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
31400 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a t);.const void *
31410 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
31420 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 atabase_name16(s
31430 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
31440 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
31450 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 qlite3_column_ta
31460 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ble_name(sqlite3
31470 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
31480 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
31490 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 _column_table_na
314a0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
314b0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 t*,int);.const c
314c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
314d0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 umn_origin_name(
314e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
314f0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a t);.const void *
31500 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f sqlite3_column_o
31510 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c rigin_name16(sql
31520 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
31530 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
31540 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 : Declared Datat
31550 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 ype Of A Query R
31560 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a esult.** METHOD:
31570 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
31580 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 .** ^(The first
31590 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b parameter is a [
315a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
315b0 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 nt]..** If this
315c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b statement is a [
315d0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
315e0 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f t and the Nth co
315f0 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 lumn of the.** r
31600 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 eturned result s
31610 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 et of that [SELE
31620 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 CT] is a table c
31630 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a olumn (not an.**
31640 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 expression or s
31650 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 ubquery) then th
31660 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 e declared type
31670 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 of the table.**
31680 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e column is return
31690 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e ed.)^ ^If the N
316a0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 th column of the
316b0 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 result set is a
316c0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 n.** expression
316d0 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 or subquery, the
316e0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 n a NULL pointer
316f0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
31700 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 ^The returned s
31710 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 tring is always
31720 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a UTF-8 encoded..*
31730 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 *.** ^(For examp
31740 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 le, given the da
31750 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a tabase schema:.*
31760 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c *.** CREATE TABL
31770 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 E t1(c1 VARIANT)
31780 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 ;.**.** and the
31790 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d following statem
317a0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c ent to be compil
317b0 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 ed:.**.** SELECT
317c0 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d c1 + 1, c1 FROM
317d0 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 t1;.**.** this
317e0 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 routine would re
317f0 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 turn the string
31800 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 "VARIANT" for th
31810 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a e second result.
31820 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 ** column (i==1)
31830 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 , and a NULL poi
31840 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 nter for the fir
31850 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e st result column
31860 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a (i==0).)^.**.**
31870 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 ^SQLite uses dy
31880 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 namic run-time t
31890 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 yping. ^So just
318a0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d because a colum
318b0 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 n.** is declared
318c0 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 to contain a pa
318d0 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f rticular type do
318e0 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 es not mean that
318f0 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f the.** data sto
31900 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 red in that colu
31910 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 mn is of the dec
31920 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c lared type. SQL
31930 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 ite is.** strong
31940 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 ly typed, but th
31950 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 e typing is dyna
31960 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 mic not static.
31970 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 ^Type.** is ass
31980 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 ociated with ind
31990 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 ividual values,
319a0 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e not with the con
319b0 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 tainers.** used
319c0 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 to hold those va
319d0 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 lues..*/.const c
319e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
319f0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c umn_decltype(sql
31a00 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
31a10 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
31a20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c ite3_column_decl
31a30 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 type16(sqlite3_s
31a40 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a tmt*,int);../*.*
31a50 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c * CAPI3REF: Eval
31a60 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 uate An SQL Stat
31a70 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a ement.** METHOD:
31a80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
31a90 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 .** After a [pre
31aa0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
31ab0 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 has been prepar
31ac0 65 64 20 75 73 69 6e 67 20 61 6e 79 20 6f 66 0a ed using any of.
31ad0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
31ae0 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
31af0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 te3_prepare_v3()
31b00 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ], [sqlite3_prep
31b10 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 are16_v2()],.**
31b20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
31b30 61 72 65 31 36 5f 76 33 28 29 5d 20 6f 72 20 6f are16_v3()] or o
31b40 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 ne of the legacy
31b50 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b .** interfaces [
31b60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
31b70 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
31b80 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 repare16()], thi
31b90 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 s function.** mu
31ba0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 st be called one
31bb0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 or more times t
31bc0 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 o evaluate the s
31bd0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 tatement..**.**
31be0 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 The details of t
31bf0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 he behavior of t
31c00 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 he sqlite3_step(
31c10 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 ) interface depe
31c20 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 nd.** on whether
31c30 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 the statement w
31c40 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e as prepared usin
31c50 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 58 22 g the newer "vX"
31c60 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 5b interfaces.** [
31c70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
31c80 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f v3()], [sqlite3_
31c90 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b prepare_v2()], [
31ca0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
31cb0 36 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 6_v3()],.** [sql
31cc0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
31cd0 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 2()] or the olde
31ce0 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 r legacy.** inte
31cf0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f rfaces [sqlite3_
31d00 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b prepare()] and [
31d10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
31d20 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 6()]. The use o
31d30 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 58 f the.** new "vX
31d40 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 " interface is r
31d50 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e ecommended for n
31d60 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ew applications
31d70 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a but the legacy.*
31d80 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c * interface will
31d90 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 continue to be
31da0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a supported..**.**
31db0 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 ^In the legacy
31dc0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 interface, the r
31dd0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c eturn value will
31de0 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 be either [SQLI
31df0 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 TE_BUSY],.** [SQ
31e00 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c LITE_DONE], [SQL
31e10 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 ITE_ROW], [SQLIT
31e20 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 E_ERROR], or [SQ
31e30 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a LITE_MISUSE]..**
31e40 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 ^With the "v2"
31e50 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f interface, any o
31e60 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 f the other [res
31e70 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a ult codes] or.**
31e80 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
31e90 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 t codes] might b
31ea0 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 e returned as we
31eb0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 ll..**.** ^[SQLI
31ec0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 TE_BUSY] means t
31ed0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 hat the database
31ee0 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 engine was unab
31ef0 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 le to acquire th
31f00 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f e.** database lo
31f10 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 cks it needs to
31f20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 do its job. ^If
31f30 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
31f40 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 s a [COMMIT].**
31f50 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 or occurs outsid
31f60 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 e of an explicit
31f70 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 transaction, th
31f80 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 en you can retry
31f90 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e the.** statemen
31fa0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 t. If the state
31fb0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 ment is not a [C
31fc0 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 OMMIT] and occur
31fd0 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 s within an.** e
31fe0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
31ff0 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f ion then you sho
32000 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 uld rollback the
32010 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 transaction bef
32020 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e ore.** continuin
32030 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 g..**.** ^[SQLIT
32040 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 E_DONE] means th
32050 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 at the statement
32060 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 has finished ex
32070 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 ecuting.** succe
32080 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 ssfully. sqlite
32090 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 3_step() should
320a0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 not be called ag
320b0 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 ain on this virt
320c0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 ual.** machine w
320d0 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c ithout first cal
320e0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 ling [sqlite3_re
320f0 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 set()] to reset
32100 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d the virtual.** m
32110 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 achine back to i
32120 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 ts initial state
32130 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
32140 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 SQL statement be
32150 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 ing executed ret
32160 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 urns any data, t
32170 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d hen [SQLITE_ROW]
32180 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
32190 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 each time a new
321a0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 row of data is r
321b0 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 eady for process
321c0 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 ing by the.** ca
321d0 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 ller. The values
321e0 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 may be accessed
321f0 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 using the [colu
32200 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 mn access functi
32210 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 ons]..** sqlite3
32220 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 _step() is calle
32230 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 d again to retri
32240 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 eve the next row
32250 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 of data..**.**
32260 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 ^[SQLITE_ERROR]
32270 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e means that a run
32280 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 -time error (suc
32290 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e h as a constrain
322a0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 t.** violation)
322b0 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 has occurred. s
322c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 qlite3_step() sh
322d0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c ould not be call
322e0 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 ed again on.** t
322f0 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f he VM. More info
32300 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 rmation may be f
32310 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 ound by calling
32320 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
32330 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 )]..** ^With the
32340 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
32350 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 e, a more specif
32360 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 ic error code (f
32370 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b or example,.** [
32380 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
32390 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d ], [SQLITE_SCHEM
323a0 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 A], [SQLITE_CORR
323b0 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 UPT], and so for
323c0 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 th).** can be ob
323d0 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e tained by callin
323e0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
323f0 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 ()] on the.** [p
32400 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
32410 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 t]. ^In the "v2
32420 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 " interface,.**
32430 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 the more specifi
32440 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 c error code is
32450 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c returned directl
32460 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 y by sqlite3_ste
32470 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 p()..**.** [SQLI
32480 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 TE_MISUSE] means
32490 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 that the this r
324a0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 outine was calle
324b0 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c d inappropriatel
324c0 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 y..** Perhaps it
324d0 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 was called on a
324e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
324f0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a ment] that has.*
32500 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b * already been [
32510 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
32520 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 | finalized] or
32530 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 on one that had
32540 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 .** previously r
32550 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
32560 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 ERROR] or [SQLIT
32570 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 E_DONE]. Or it
32580 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 could.** be the
32590 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 case that the sa
325a0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
325b0 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 ection is being
325c0 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a used by two or.*
325d0 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 * more threads a
325e0 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e t the same momen
325f0 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a t in time..**.**
32600 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e For all version
32610 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 s of SQLite up t
32620 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 o and including
32630 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 3.6.23.1, a call
32640 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
32650 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 reset()] was req
32660 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 uired after sqli
32670 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 te3_step() retur
32680 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 ned anything.**
32690 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
326a0 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 TE_ROW] before a
326b0 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e ny subsequent in
326c0 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 vocation of.** s
326d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
326e0 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 Failure to reset
326f0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
32700 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a atement using .*
32710 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
32720 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 ()] would result
32730 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d in an [SQLITE_M
32740 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 ISUSE] return fr
32750 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 om.** sqlite3_st
32760 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 ep(). But after
32770 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 [version 3.6.23
32780 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 .1] ([dateof:3.6
32790 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 .23.1],.** sqlit
327a0 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a e3_step() began.
327b0 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 ** calling [sqli
327c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 te3_reset()] aut
327d0 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 omatically in th
327e0 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 is circumstance
327f0 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 rather.** than r
32800 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 eturning [SQLITE
32810 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 _MISUSE]. This
32820 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 is not considere
32830 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 d a compatibilit
32840 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 y.** break becau
32850 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 se any applicati
32860 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 on that ever rec
32870 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f eives an SQLITE_
32880 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 MISUSE error.**
32890 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 is broken by def
328a0 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 inition. The [S
328b0 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 QLITE_OMIT_AUTOR
328c0 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 ESET] compile-ti
328d0 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e me option.** can
328e0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 be used to rest
328f0 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 ore the legacy b
32900 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c ehavior..**.** <
32910 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 b>Goofy Interfac
32920 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 e Alert:</b> In
32930 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 the legacy inter
32940 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 face, the sqlite
32950 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 3_step().** API
32960 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 always returns a
32970 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 generic error c
32980 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 ode, [SQLITE_ERR
32990 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 OR], following a
329a0 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 ny.** error othe
329b0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 r than [SQLITE_B
329c0 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 USY] and [SQLITE
329d0 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d _MISUSE]. You m
329e0 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c ust call.** [sql
329f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
32a00 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
32a10 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 ze()] in order t
32a20 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 o find one of th
32a30 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 e.** specific [e
32a40 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 rror codes] that
32a50 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 better describe
32a60 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 s the error..**
32a70 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 We admit that th
32a80 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 is is a goofy de
32a90 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c sign. The probl
32aa0 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 em has been fixe
32ab0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 d.** with the "v
32ac0 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 2" interface. I
32ad0 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c f you prepare al
32ae0 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 l of your SQL st
32af0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e atements.** usin
32b00 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
32b10 72 65 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71 6c re_v3()] or [sql
32b20 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
32b30 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 )].** or [sqlite
32b40 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
32b50 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ] or [sqlite3_pr
32b60 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e epare16_v3()] in
32b70 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 stead.** of the
32b80 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f legacy [sqlite3_
32b90 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b prepare()] and [
32ba0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
32bb0 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 6()] interfaces,
32bc0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 .** then the mor
32bd0 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f e specific [erro
32be0 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 r codes] are ret
32bf0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a urned directly.*
32c00 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 * by sqlite3_ste
32c10 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 p(). The use of
32c20 20 74 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 the "vX" interf
32c30 61 63 65 73 20 69 73 20 72 65 63 6f 6d 6d 65 6e aces is recommen
32c40 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ded..*/.int sqli
32c50 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 te3_step(sqlite3
32c60 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
32c70 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
32c80 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 of columns in a
32c90 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d result set.** M
32ca0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
32cb0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 tmt.**.** ^The s
32cc0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
32cd0 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 t(P) interface r
32ce0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
32cf0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
32d00 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 the.** current r
32d10 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ow of the result
32d20 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 set of [prepare
32d30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a d statement] P..
32d40 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 ** ^If prepared
32d50 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 statement P does
32d60 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 not have result
32d70 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 s ready to retur
32d80 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 n.** (via calls
32d90 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
32da0 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c column_int | sql
32db0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d ite3_column_*()]
32dc0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 of.** interface
32dd0 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f s) then sqlite3_
32de0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 data_count(P) re
32df0 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 turns 0..** ^The
32e00 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
32e10 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 unt(P) routine a
32e20 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 lso returns 0 if
32e30 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 P is a NULL poi
32e40 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 nter..** ^The sq
32e50 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
32e60 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 (P) routine retu
32e70 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 rns 0 if the pre
32e80 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a vious call to.**
32e90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 [sqlite3_step](
32ea0 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c P) returned [SQL
32eb0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 ITE_DONE]. ^The
32ec0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
32ed0 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 unt(P).** will r
32ee0 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 eturn non-zero i
32ef0 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 f previous call
32f00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
32f10 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a ](P) returned.**
32f20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 [SQLITE_ROW], e
32f30 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 xcept in the cas
32f40 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 e of the [PRAGMA
32f50 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 incremental_vac
32f60 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 uum].** where it
32f70 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
32f80 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 zero since each
32f90 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c step of that mul
32fa0 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d ti-step.** pragm
32fb0 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 a returns 0 colu
32fc0 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a mns of data..**.
32fd0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
32fe0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 lite3_column_cou
32ff0 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c nt()].*/.int sql
33000 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
33010 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
33020 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
33030 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 I3REF: Fundament
33040 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 al Datatypes.**
33050 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 KEYWORDS: SQLITE
33060 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 _TEXT.**.** ^(Ev
33070 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c ery value in SQL
33080 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 ite has one of f
33090 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 ive fundamental
330a0 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a datatypes:.**.**
330b0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 <ul>.** <li> 64
330c0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
330d0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 ger.** <li> 64-b
330e0 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 it IEEE floating
330f0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a point number.**
33100 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 <li> string.**
33110 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 <li> BLOB.** <li
33120 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 > NULL.** </ul>)
33130 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f ^.**.** These co
33140 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 nstants are code
33150 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 s for each of th
33160 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a ose types..**.**
33170 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 Note that the S
33180 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 QLITE_TEXT const
33190 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 ant was also use
331a0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 d in SQLite vers
331b0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 ion 2.** for a c
331c0 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 ompletely differ
331d0 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f ent meaning. So
331e0 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b ftware that link
331f0 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a s against both.*
33200 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e * SQLite version
33210 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 2 and SQLite ve
33220 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 rsion 3 should u
33230 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c se SQLITE3_TEXT,
33240 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 not.** SQLITE_T
33250 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 EXT..*/.#define
33260 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 SQLITE_INTEGER
33270 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
33280 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 _FLOAT 2.#def
33290 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 ine SQLITE_BLOB
332a0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
332b0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a LITE_NULL 5.
332c0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 #ifdef SQLITE_TE
332d0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 XT.# undef SQLIT
332e0 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 E_TEXT.#else.# d
332f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 efine SQLITE_TEX
33300 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 T 3.#endif.#
33310 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 define SQLITE3_T
33320 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a EXT 3../*.**
33330 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c CAPI3REF: Resul
33340 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 t Values From A
33350 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 Query.** KEYWORD
33360 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 S: {column acces
33370 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 s functions}.**
33380 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
33390 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 stmt.**.** <b>Su
333a0 6d 6d 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 mmary:</b>.** <b
333b0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65 lockquote><table
333c0 20 62 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70 61 border=0 cellpa
333d0 64 64 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61 63 dding=0 cellspac
333e0 69 6e 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 ing=0>.** <tr><t
333f0 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c d><b>sqlite3_col
33400 75 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e umn_blob</b><td>
33410 26 72 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20 72 →<td>BLOB r
33420 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 esult.** <tr><td
33430 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ><b>sqlite3_colu
33440 6d 6e 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64 mn_double</b><td
33450 3e 26 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c 20 >→<td>REAL
33460 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 result.** <tr><t
33470 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c d><b>sqlite3_col
33480 75 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26 umn_int</b><td>&
33490 72 61 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74 20 rarr;<td>32-bit
334a0 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a INTEGER result.*
334b0 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c * <tr><td><b>sql
334c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 ite3_column_int6
334d0 34 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 4</b><td>→<
334e0 74 64 3e 36 34 2d 62 69 74 20 49 4e 54 45 47 45 td>64-bit INTEGE
334f0 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e R result.** <tr>
33500 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 <td><b>sqlite3_c
33510 6f 6c 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74 olumn_text</b><t
33520 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d d>→<td>UTF-
33530 38 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 8 TEXT result.**
33540 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 <tr><td><b>sqli
33550 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
33560 36 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 6</b><td>→<
33570 74 64 3e 55 54 46 2d 31 36 20 54 45 58 54 20 72 td>UTF-16 TEXT r
33580 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 esult.** <tr><td
33590 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ><b>sqlite3_colu
335a0 6d 6e 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e mn_value</b><td>
335b0 26 72 61 72 72 3b 3c 74 64 3e 54 68 65 20 72 65 →<td>The re
335c0 73 75 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20 5b sult as an .** [
335d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75 6e sqlite3_value|un
335e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
335f0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 3_value] object.
33600 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62 73 .** <tr><td>&nbs
33610 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e p;<td> <td>
33620 26 6e 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 .** <tr><t
33630 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c d><b>sqlite3_col
33640 75 6d 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74 64 umn_bytes</b><td
33650 3e 26 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65 20 >→<td>Size
33660 6f 66 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20 of a BLOB.** or
33670 61 20 55 54 46 2d 38 20 54 45 58 54 20 72 65 73 a UTF-8 TEXT res
33680 75 6c 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 ult in bytes.**
33690 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 <tr><td><b>sqlit
336a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
336b0 36 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f 62 6 </b
336c0 3e 0a 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b 26 >.** <td>→&
336d0 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e 53 nbsp; <td>S
336e0 69 7a 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a 2a ize of UTF-16.**
336f0 20 54 45 58 54 20 69 6e 20 62 79 74 65 73 0a 2a TEXT in bytes.*
33700 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c * <tr><td><b>sql
33710 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
33720 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 </b><td>→<t
33730 64 3e 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61 74 d>Default.** dat
33740 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 atype of the res
33750 75 6c 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c ult.** </table><
33760 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
33770 2a 2a 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c 2f ** <b>Details:</
33780 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 b>.**.** ^These
33790 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
337a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 information abou
337b0 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d t a single colum
337c0 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 n of the current
337d0 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f .** result row o
337e0 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 f a query. ^In
337f0 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 every case the f
33800 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
33810 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
33820 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
33830 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 tatement] that i
33840 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 s being evaluate
33850 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f d (the [sqlite3_
33860 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 stmt*].** that w
33870 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d as returned from
33880 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
33890 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f e_v2()] or one o
338a0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a f its variants).
338b0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e ** and the secon
338c0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
338d0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 e index of the c
338e0 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 olumn for which
338f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 information.** s
33900 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 hould be returne
33910 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 d. ^The leftmost
33920 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 column of the r
33930 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 esult set has th
33940 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 e index 0..** ^T
33950 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
33960 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 umns in the resu
33970 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d lt can be determ
33980 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 ined using.** [s
33990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f qlite3_column_co
339a0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 unt()]..**.** If
339b0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
339c0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 nt does not curr
339d0 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 ently point to a
339e0 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 valid row, or i
339f0 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 f the.** column
33a00 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
33a10 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c range, the resul
33a20 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a t is undefined..
33a30 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
33a40 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 s may only be ca
33a50 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f lled when the mo
33a60 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
33a70 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 o.** [sqlite3_st
33a80 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e ep()] has return
33a90 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 ed [SQLITE_ROW]
33aa0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b and neither.** [
33ab0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
33ac0 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 nor [sqlite3_fi
33ad0 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 nalize()] have b
33ae0 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 een called subse
33af0 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 quently..** If a
33b00 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
33b10 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
33b20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 after [sqlite3_r
33b30 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
33b40 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
33b50 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c )] or after [sql
33b60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
33b70 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d returned.** som
33b80 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 ething other tha
33b90 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 n [SQLITE_ROW],
33ba0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
33bb0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 undefined..** If
33bc0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
33bd0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
33be0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
33bf0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a e3_finalize()].*
33c00 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f * are called fro
33c10 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 m a different th
33c20 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f read while any o
33c30 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
33c40 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c .** are pending,
33c50 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
33c60 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
33c70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
33c80 20 73 69 78 20 69 6e 74 65 72 66 61 63 65 73 20 six interfaces
33c90 28 5f 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c (_blob, _double,
33ca0 20 5f 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20 5f _int, _int64, _
33cb0 74 65 78 74 2c 20 61 6e 64 20 5f 74 65 78 74 31 text, and _text1
33cc0 36 29 0a 2a 2a 20 65 61 63 68 20 72 65 74 75 72 6).** each retur
33cd0 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 n the value of a
33ce0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 result column i
33cf0 6e 20 61 20 73 70 65 63 69 66 69 63 20 64 61 74 n a specific dat
33d00 61 20 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a 2a a format. If.**
33d10 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 the result colu
33d20 6d 6e 20 69 73 20 6e 6f 74 20 69 6e 69 74 69 61 mn is not initia
33d30 6c 6c 79 20 69 6e 20 74 68 65 20 72 65 71 75 65 lly in the reque
33d40 73 74 65 64 20 66 6f 72 6d 61 74 20 28 66 6f 72 sted format (for
33d50 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20 example,.** if
33d60 74 68 65 20 71 75 65 72 79 20 72 65 74 75 72 6e the query return
33d70 73 20 61 6e 20 69 6e 74 65 67 65 72 20 62 75 74 s an integer but
33d80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c the sqlite3_col
33d90 75 6d 6e 5f 74 65 78 74 28 29 20 69 6e 74 65 72 umn_text() inter
33da0 66 61 63 65 0a 2a 2a 20 69 73 20 75 73 65 64 20 face.** is used
33db0 74 6f 20 65 78 74 72 61 63 74 20 74 68 65 20 76 to extract the v
33dc0 61 6c 75 65 29 20 74 68 65 6e 20 61 6e 20 61 75 alue) then an au
33dd0 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e tomatic type con
33de0 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f version is perfo
33df0 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 rmed..**.** ^The
33e00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
33e10 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 type() routine r
33e20 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 eturns the.** [S
33e30 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 QLITE_INTEGER |
33e40 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 datatype code] f
33e50 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 or the initial d
33e60 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 ata type.** of t
33e70 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e he result column
33e80 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 . ^The returned
33e90 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 value is one of
33ea0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
33eb0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c ],.** [SQLITE_FL
33ec0 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 OAT], [SQLITE_TE
33ed0 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f XT], [SQLITE_BLO
33ee0 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e B], or [SQLITE_N
33ef0 55 4c 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 74 ULL]..** The ret
33f00 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 73 71 6c urn value of sql
33f10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
33f20 28 29 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 () can be used t
33f30 6f 20 64 65 63 69 64 65 20 77 68 69 63 68 0a 2a o decide which.*
33f40 2a 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 73 * of the first s
33f50 69 78 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f ix interface sho
33f60 75 6c 64 20 62 65 20 75 73 65 64 20 74 6f 20 65 uld be used to e
33f70 78 74 72 61 63 74 20 74 68 65 20 63 6f 6c 75 6d xtract the colum
33f80 6e 20 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 n value..** The
33f90 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
33fa0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
33fb0 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 _type() is only
33fc0 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f meaningful if no
33fd0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20 74 79 .** automatic ty
33fe0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 pe conversions h
33ff0 61 76 65 20 6f 63 63 75 72 72 65 64 20 66 6f 72 ave occurred for
34000 20 74 68 65 20 76 61 6c 75 65 20 69 6e 20 71 75 the value in qu
34010 65 73 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74 estion. .** Aft
34020 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 er a type conver
34030 73 69 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c 74 sion, the result
34040 20 6f 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 of calling sqli
34050 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
34060 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 ).** is undefine
34070 64 2c 20 74 68 6f 75 67 68 20 68 61 72 6d 6c 65 d, though harmle
34080 73 73 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 ss. Future.** v
34090 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
340a0 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 e may change the
340b0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c behavior of sql
340c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
340d0 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ().** following
340e0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f a type conversio
340f0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 n..**.** If the
34100 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 result is a BLOB
34110 20 6f 72 20 61 20 54 45 58 54 20 73 74 72 69 6e or a TEXT strin
34120 67 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 g, then the sqli
34130 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
34140 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
34150 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
34160 29 20 69 6e 74 65 72 66 61 63 65 73 20 63 61 6e ) interfaces can
34170 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 74 65 be used to dete
34180 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 0a 2a rmine the size.*
34190 2a 20 6f 66 20 74 68 61 74 20 42 4c 4f 42 20 6f * of that BLOB o
341a0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 r string..**.**
341b0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
341c0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
341d0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 8 string then th
341e0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
341f0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 _bytes().** rout
34200 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
34210 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
34220 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 in that BLOB or
34230 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
34240 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 he result is a U
34250 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 TF-16 string, th
34260 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
34270 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 n_bytes() conver
34280 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 ts.** the string
34290 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 to UTF-8 and th
342a0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e en returns the n
342b0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a umber of bytes..
342c0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
342d0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 t is a numeric v
342e0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 alue then sqlite
342f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
34300 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 uses.** [sqlite
34310 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 3_snprintf()] to
34320 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 convert that va
34330 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 lue to a UTF-8 s
34340 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
34350 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
34360 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
34370 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
34380 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 the result is NU
34390 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 LL, then sqlite3
343a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
343b0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
343c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
343d0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 lt is a BLOB or
343e0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 UTF-16 string th
343f0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 en the sqlite3_c
34400 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a olumn_bytes16().
34410 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
34420 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
34430 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 bytes in that B
34440 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a LOB or string..*
34450 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
34460 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 is a UTF-8 stri
34470 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ng, then sqlite3
34480 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
34490 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 ) converts.** th
344a0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d e string to UTF-
344b0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 16 and then retu
344c0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
344d0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 f bytes..** ^If
344e0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
344f0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 numeric value th
34500 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
34510 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 n_bytes16() uses
34520 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 .** [sqlite3_snp
34530 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 rintf()] to conv
34540 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 ert that value t
34550 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e o a UTF-16 strin
34560 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a g and returns.**
34570 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
34580 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 ytes in that str
34590 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
345a0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 result is NULL,
345b0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
345c0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 umn_bytes16() re
345d0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a turns zero..**.*
345e0 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 * ^The values re
345f0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
34600 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
34610 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 )] and .** [sqli
34620 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
34630 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 16()] do not inc
34640 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 lude the zero te
34650 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 rminators at the
34660 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 end.** of the s
34670 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 tring. ^For cla
34680 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 rity: the values
34690 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
346a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
346b0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 bytes()] and [sq
346c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
346d0 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 es16()] are the
346e0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 number of.** byt
346f0 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 es in the string
34700 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
34710 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a of characters..
34720 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 **.** ^Strings r
34730 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
34740 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
34750 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
34760 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a umn_text16(),.**
34770 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 even empty stri
34780 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 ngs, are always
34790 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e zero-terminated.
347a0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a ^The return.**
347b0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
347c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
347d0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e ) for a zero-len
347e0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 gth BLOB is a NU
347f0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
34800 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 * <b>Warning:</b
34810 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 > ^The object re
34820 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
34830 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
34840 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 )] is an.** [unp
34850 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
34860 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 _value] object.
34870 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 In a multithrea
34880 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c ded environment,
34890 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 .** an unprotect
348a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
348b0 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 object may only
348c0 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 be used safely
348d0 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 with.** [sqlite3
348e0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 _bind_value()] a
348f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 nd [sqlite3_resu
34900 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 lt_value()]..**
34910 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 If the [unprotec
34920 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
34930 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e e] object return
34940 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 ed by.** [sqlite
34950 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 3_column_value()
34960 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 ] is used in any
34970 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c other way, incl
34980 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 uding calls.** t
34990 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 o routines like
349a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 [sqlite3_value_i
349b0 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f nt()], [sqlite3_
349c0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a value_text()],.*
349d0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 * or [sqlite3_va
349e0 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 lue_bytes()], th
349f0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f e behavior is no
34a00 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a t threadsafe..**
34a10 20 48 65 6e 63 65 2c 20 74 68 65 20 73 71 6c 69 Hence, the sqli
34a20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
34a30 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 () interface.**
34a40 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 is normally only
34a50 20 75 73 65 66 75 6c 20 77 69 74 68 69 6e 20 74 useful within t
34a60 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
34a70 6e 20 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69 63 n of .** [applic
34a80 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
34a90 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 20 L functions] or
34aa0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d [virtual tables]
34ab0 2c 20 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a 20 , not within.**
34ac0 74 6f 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69 63 top-level applic
34ad0 61 74 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a ation code..**.*
34ae0 2a 20 54 68 65 20 74 68 65 73 65 20 72 6f 75 74 * The these rout
34af0 69 6e 65 73 20 6d 61 79 20 61 74 74 65 6d 70 74 ines may attempt
34b00 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
34b10 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 datatype of the
34b20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20 result..** ^For
34b30 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 example, if the
34b40 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
34b50 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 ntation is FLOAT
34b60 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 and a text resu
34b70 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 lt.** is request
34b80 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 ed, [sqlite3_snp
34b90 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 rintf()] is used
34ba0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 internally to p
34bb0 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f erform the.** co
34bc0 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 nversion automat
34bd0 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 ically. ^(The f
34be0 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 ollowing table d
34bf0 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 etails the conve
34c00 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 rsions.** that a
34c10 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a re applied:.**.*
34c20 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a * <blockquote>.*
34c30 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d * <table border=
34c40 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e "1">.** <tr><th>
34c50 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 Internal<br>Typ
34c60 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 e <th> Requested
34c70 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 <br>Type <th> C
34c80 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 onversion.**.**
34c90 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
34ca0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
34cb0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
34cc0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 0.** <tr><td> N
34cd0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f ULL <td> FLO
34ce0 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c AT <td> Resul
34cf0 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e t is 0.0.** <tr>
34d00 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
34d10 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 d> TEXT <td
34d20 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 > Result is a NU
34d30 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 LL pointer.** <t
34d40 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
34d50 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
34d60 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 td> Result is a
34d70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
34d80 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
34d90 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
34da0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 <td> Convert fr
34db0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c om integer to fl
34dc0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 oat.** <tr><td>
34dd0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 INTEGER <td>
34de0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 TEXT <td> ASC
34df0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 II rendering of
34e00 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c the integer.** <
34e10 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
34e20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
34e30 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 <td> Same as INT
34e40 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 EGER->TEXT.** <t
34e50 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 r><td> FLOAT
34e60 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
34e70 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e td> [CAST] to IN
34e80 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 TEGER.** <tr><td
34e90 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
34ea0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
34eb0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f SCII rendering o
34ec0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c f the float.** <
34ed0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 tr><td> FLOAT
34ee0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
34ef0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 <td> [CAST] to B
34f00 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 LOB.** <tr><td>
34f10 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e TEXT <td> IN
34f20 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 TEGER <td> [CA
34f30 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a ST] to INTEGER.*
34f40 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
34f50 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <td> FLOAT
34f60 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 <td> [CAST] t
34f70 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 o REAL.** <tr><t
34f80 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
34f90 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
34fa0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 No change.** <tr
34fb0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c ><td> BLOB <
34fc0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
34fd0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 d> [CAST] to INT
34fe0 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e EGER.** <tr><td>
34ff0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 BLOB <td>
35000 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 FLOAT <td> [C
35010 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 AST] to REAL.**
35020 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
35030 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
35040 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f <td> Add a zero
35050 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e terminator if n
35060 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 eeded.** </table
35070 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 >.** </blockquot
35080 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 e>)^.**.** Note
35090 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 that when type c
350a0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 onversions occur
350b0 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 , pointers retur
350c0 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 ned by prior.**
350d0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
350e0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 _column_blob(),
350f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
35100 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a ext(), and/or.**
35110 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
35120 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 text16() may be
35130 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 invalidated..**
35140 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 Type conversions
35150 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 and pointer inv
35160 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 alidations might
35170 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 occur.** in the
35180 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 following cases
35190 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
351a0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c <li> The initial
351b0 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c content is a BL
351c0 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 OB and sqlite3_c
351d0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a olumn_text() or.
351e0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f ** sqlite3_
351f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
35200 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 is called. A ze
35210 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 ro-terminator mi
35220 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 ght.** need
35230 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 to be added to
35240 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e the string.</li>
35250 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 .** <li> The ini
35260 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 tial content is
35270 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 UTF-8 text and s
35280 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
35290 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 tes16() or.**
352a0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d sqlite3_colum
352b0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 n_text16() is ca
352c0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 lled. The conte
352d0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 nt must be conve
352e0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 rted.** to
352f0 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 UTF-16.</li>.**
35300 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c <li> The initial
35310 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d content is UTF-
35320 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 16 text and sqli
35330 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
35340 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
35350 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
35360 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 t() is called.
35370 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 The content must
35380 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a be converted.**
35390 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c to UTF-8.<
353a0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a /li>.** </ul>.**
353b0 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 .** ^Conversions
353c0 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 between UTF-16b
353d0 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 e and UTF-16le a
353e0 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 re always done i
353f0 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a n place and do.*
35400 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 * not invalidate
35410 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 a prior pointer
35420 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 , though of cour
35430 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f se the content o
35440 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 f the buffer.**
35450 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 that the prior p
35460 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 ointer reference
35470 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e s will have been
35480 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 modified. Othe
35490 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f r kinds.** of co
354a0 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e nversion are don
354b0 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 e in place when
354c0 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 it is possible,
354d0 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 but sometimes th
354e0 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f ey.** are not po
354f0 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 ssible and in th
35500 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 ose cases prior
35510 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 pointers are inv
35520 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 alidated..**.**
35530 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 The safest polic
35540 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 y is to invoke t
35550 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a hese routines.**
35560 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 in one of the f
35570 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a ollowing ways:.*
35580 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c *.** <ul>.** <l
35590 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e i>sqlite3_column
355a0 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 _text() followed
355b0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
355c0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a mn_bytes()</li>.
355d0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f ** <li>sqlite3_
355e0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f column_blob() fo
355f0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 llowed by sqlite
35600 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
35610 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 </li>.** <li>sq
35620 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
35630 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 t16() followed b
35640 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
35650 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a _bytes16()</li>.
35660 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 ** </ul>.**.** I
35670 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 n other words, y
35680 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 ou should call s
35690 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
356a0 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 xt(),.** sqlite3
356b0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 _column_blob(),
356c0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
356d0 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 n_text16() first
356e0 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 to force the re
356f0 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 sult.** into the
35700 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c desired format,
35710 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c then invoke sql
35720 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
35730 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 s() or.** sqlite
35740 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
35750 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 () to find the s
35760 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ize of the resul
35770 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 t. Do not mix c
35780 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 alls.** to sqlit
35790 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
357a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
357b0 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 mn_blob() with c
357c0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 alls to.** sqlit
357d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
357e0 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6(), and do not
357f0 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c mix calls to sql
35800 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
35810 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 16().** with cal
35820 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ls to sqlite3_co
35830 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a lumn_bytes()..**
35840 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 .** ^The pointer
35850 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 s returned are v
35860 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 alid until a typ
35870 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 e conversion occ
35880 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 urs as.** descri
35890 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e bed above, or un
358a0 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 til [sqlite3_ste
358b0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 p()] or [sqlite3
358c0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 _reset()] or.**
358d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
358e0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 e()] is called.
358f0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 ^The memory spa
35900 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 ce used to hold
35910 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 strings.** and B
35920 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 LOBs is freed au
35930 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f tomatically. Do
35940 20 6e 6f 74 20 70 61 73 73 20 74 68 65 20 70 6f not pass the po
35950 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a inters returned.
35960 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ** from [sqlite3
35970 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c _column_blob()],
35980 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
35990 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 _text()], etc. i
359a0 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nto.** [sqlite3_
359b0 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e free()]..**.** ^
359c0 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c (If a memory all
359d0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 ocation error oc
359e0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 curs during the
359f0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e evaluation of an
35a00 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f y.** of these ro
35a10 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c utines, a defaul
35a20 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 t value is retur
35a30 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c ned. The defaul
35a40 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 t value.** is ei
35a50 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 ther the integer
35a60 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 0, the floating
35a70 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e point number 0.
35a80 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 0, or a NULL.**
35a90 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 pointer. Subseq
35aa0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 uent calls to [s
35ab0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
35ac0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a ] will return.**
35ad0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e [SQLITE_NOMEM].
35ae0 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 )^.*/.const void
35af0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
35b00 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 _blob(sqlite3_st
35b10 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
35b20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 double sqlite3_c
35b30 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c olumn_double(sql
35b40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
35b50 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 iCol);.int sqlit
35b60 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 e3_column_int(sq
35b70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
35b80 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f iCol);.sqlite3_
35b90 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f int64 sqlite3_co
35ba0 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 lumn_int64(sqlit
35bb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
35bc0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 ol);.const unsig
35bd0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 ned char *sqlite
35be0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 3_column_text(sq
35bf0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
35c00 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f iCol);.const vo
35c10 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
35c20 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 mn_text16(sqlite
35c30 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
35c40 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 l);.sqlite3_valu
35c50 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e *sqlite3_colum
35c60 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f n_value(sqlite3_
35c70 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
35c80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f ;.int sqlite3_co
35c90 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 lumn_bytes(sqlit
35ca0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
35cb0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ol);.int sqlite3
35cc0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
35cd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
35ce0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 nt iCol);.int sq
35cf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
35d00 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
35d10 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a int iCol);../*.
35d20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 ** CAPI3REF: Des
35d30 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 troy A Prepared
35d40 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
35d50 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 .** DESTRUCTOR:
35d60 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
35d70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
35d80 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 finalize() funct
35d90 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f ion is called to
35da0 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 delete a [prepa
35db0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
35dc0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 ** ^If the most
35dd0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f recent evaluatio
35de0 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 n of the stateme
35df0 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e nt encountered n
35e00 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 o errors.** or i
35e10 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
35e20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 is never been ev
35e30 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 aluated, then sq
35e40 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
35e50 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 returns.** SQLI
35e60 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 TE_OK. ^If the
35e70 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c most recent eval
35e80 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d uation of statem
35e90 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 ent S failed, th
35ea0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 en.** sqlite3_fi
35eb0 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e nalize(S) return
35ec0 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 s the appropriat
35ed0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f e [error code] o
35ee0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 r.** [extended e
35ef0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a rror code]..**.*
35f00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 * ^The sqlite3_f
35f10 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 inalize(S) routi
35f20 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 ne can be called
35f30 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 at any point du
35f40 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 ring.** the life
35f50 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 cycle of [prepa
35f60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
35f70 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 :.** before stat
35f80 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 ement S is ever
35f90 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 evaluated, after
35fa0 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 .** one or more
35fb0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
35fc0 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 3_reset()], or a
35fd0 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a fter any call.**
35fe0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
35ff0 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 p()] regardless
36000 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
36010 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 t the statement
36020 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 has.** completed
36030 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a execution..**.*
36040 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 * ^Invoking sqli
36050 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f te3_finalize() o
36060 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 n a NULL pointer
36070 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e is a harmless n
36080 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 o-op..**.** The
36090 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
360a0 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 finalize every
360b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
360c0 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f ent] in order to
360d0 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 avoid.** resour
360e0 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 ce leaks. It is
360f0 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f a grievous erro
36100 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 r for the applic
36110 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 ation to try to
36120 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 use.** a prepare
36130 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 d statement afte
36140 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 r it has been fi
36150 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 nalized. Any us
36160 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a e of a prepared.
36170 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 ** statement aft
36180 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 er it has been f
36190 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 inalized can res
361a0 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 ult in undefined
361b0 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 and.** undesira
361c0 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 ble behavior suc
361d0 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 h as segfaults a
361e0 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 nd heap corrupti
361f0 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 on..*/.int sqlit
36200 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 e3_finalize(sqli
36210 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
36220 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
36230 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 F: Reset A Prepa
36240 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 red Statement Ob
36250 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ject.** METHOD:
36260 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
36270 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
36280 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 eset() function
36290 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 is called to res
362a0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 et a [prepared s
362b0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a tatement].** obj
362c0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 ect back to its
362d0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 initial state, r
362e0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 eady to be re-ex
362f0 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 ecuted..** ^Any
36300 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 SQL statement va
36310 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 riables that had
36320 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f values bound to
36330 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 them using.** t
36340 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 he [sqlite3_bind
36350 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f _blob | sqlite3_
36360 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 bind_*() API] re
36370 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 tain their value
36380 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 s..** Use [sqlit
36390 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 e3_clear_binding
363a0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 s()] to reset th
363b0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a e bindings..**.*
363c0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
363d0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 reset(S)] interf
363e0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b ace resets the [
363f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
36400 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f nt] S.** back to
36410 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f the beginning o
36420 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a f its program..*
36430 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 *.** ^If the mos
36440 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
36450 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
36460 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 )] for the.** [p
36470 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
36480 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 t] S returned [S
36490 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 QLITE_ROW] or [S
364a0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 QLITE_DONE],.**
364b0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 or if [sqlite3_s
364c0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 tep(S)] has neve
364d0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 r before been ca
364e0 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 lled on S,.** th
364f0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 en [sqlite3_rese
36500 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 t(S)] returns [S
36510 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a QLITE_OK]..**.**
36520 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ^If the most re
36530 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 cent call to [sq
36540 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 lite3_step(S)] f
36550 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 or the.** [prepa
36560 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
36570 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 indicated an er
36580 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 ror, then.** [sq
36590 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
365a0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f returns an appro
365b0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f priate [error co
365c0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 de]..**.** ^The
365d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
365e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 )] interface doe
365f0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 s not change the
36600 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e values.** of an
36610 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f y [sqlite3_bind_
36620 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f blob|bindings] o
36630 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 n the [prepared
36640 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f statement] S..*/
36650 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 .int sqlite3_res
36660 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 et(sqlite3_stmt
36670 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
36680 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 CAPI3REF: Create
36690 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c Or Redefine SQL
366a0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 Functions.** KE
366b0 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f YWORDS: {functio
366c0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 n creation routi
366d0 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 nes}.** KEYWORDS
366e0 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 : {application-d
366f0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
36700 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ion}.** KEYWORDS
36710 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 : {application-d
36720 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
36730 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a ions}.** METHOD:
36740 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
36750 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
36760 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e (collectively kn
36770 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e own as "function
36780 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e creation routin
36790 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 es").** are used
367a0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 to add SQL func
367b0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 tions or aggrega
367c0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 tes or to redefi
367d0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a ne the behavior.
367e0 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 ** of existing S
367f0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 QL functions or
36800 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 aggregates. The
36810 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 only difference
36820 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 s between.** the
36830 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
36840 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e the text encodin
36850 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a g expected for.*
36860 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 * the second par
36870 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 ameter (the name
36880 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e of the function
36890 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a being created).
368a0 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 ** and the prese
368b0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f nce or absence o
368c0 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 f a destructor c
368d0 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 allback for.** t
368e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
368f0 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ata pointer..**.
36900 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 ** ^The first pa
36910 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b rameter is the [
36920 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
36930 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 ion] to which th
36940 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f e SQL.** functio
36950 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 n is to be added
36960 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 . ^If an applic
36970 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 ation uses more
36980 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 than one databas
36990 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e.** connection
369a0 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e then application
369b0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
369c0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 ctions must be a
369d0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 dded.** to each
369e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
369f0 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a ion separately..
36a00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e **.** ^The secon
36a10 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
36a20 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 he name of the S
36a30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 QL function to b
36a40 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 e created or.**
36a50 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 redefined. ^The
36a60 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e length of the n
36a70 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 ame is limited t
36a80 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 o 255 bytes in a
36a90 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 UTF-8.** repres
36aa0 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 entation, exclus
36ab0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d ive of the zero-
36ac0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f terminator. ^No
36ad0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 te that the name
36ae0 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 .** length limit
36af0 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 is in UTF-8 byt
36b00 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 es, not characte
36b10 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 rs nor UTF-16 by
36b20 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 tes. .** ^Any a
36b30 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 ttempt to create
36b40 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 a function with
36b50 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a a longer name.*
36b60 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e * will result in
36b70 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
36b80 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e being returned.
36b90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 .**.** ^The thir
36ba0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 d parameter (nAr
36bb0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d g).** is the num
36bc0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 ber of arguments
36bd0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 that the SQL fu
36be0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 nction or.** agg
36bf0 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 regate takes. ^I
36c00 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 f this parameter
36c10 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 is -1, then the
36c20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 SQL function or
36c30 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 .** aggregate ma
36c40 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 y take any numbe
36c50 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 r of arguments b
36c60 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 etween 0 and the
36c70 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 limit.** set by
36c80 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d [sqlite3_limit]
36c90 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 ([SQLITE_LIMIT_F
36ca0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 UNCTION_ARG]).
36cb0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 If the third.**
36cc0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 parameter is les
36cd0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 s than -1 or gre
36ce0 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 ater than 127 th
36cf0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
36d00 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e is.** undefined.
36d10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 .**.** ^The four
36d20 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 th parameter, eT
36d30 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 extRep, specifie
36d40 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 s what.** [SQLIT
36d50 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e E_UTF8 | text en
36d60 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c coding] this SQL
36d70 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 function prefer
36d80 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 s for.** its par
36d90 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 ameters. The ap
36da0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
36db0 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 set this parame
36dc0 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 ter to.** [SQLIT
36dd0 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 E_UTF16LE] if th
36de0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 e function imple
36df0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 mentation invoke
36e00 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 s .** [sqlite3_v
36e10 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d alue_text16le()]
36e20 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 on an input, or
36e30 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 [SQLITE_UTF16BE
36e40 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c ] if the.** impl
36e50 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b ementation invok
36e60 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 es [sqlite3_valu
36e70 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e e_text16be()] on
36e80 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a an input, or.**
36e90 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 [SQLITE_UTF16]
36ea0 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 if [sqlite3_valu
36eb0 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 e_text16()] is u
36ec0 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f sed, or [SQLITE_
36ed0 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 UTF8].** otherwi
36ee0 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 se. ^The same S
36ef0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 QL function may
36f00 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 be registered mu
36f10 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 ltiple times usi
36f20 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 ng.** different
36f30 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 preferred text e
36f40 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 ncodings, with d
36f50 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 ifferent impleme
36f60 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 ntations for.**
36f70 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a each encoding..*
36f80 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 * ^When multiple
36f90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
36fa0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e of the same fun
36fb0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 ction are availa
36fc0 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 ble, SQLite.** w
36fd0 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 ill pick the one
36fe0 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 that involves t
36ff0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 he least amount
37000 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 of data conversi
37010 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 on..**.** ^The f
37020 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
37030 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 may optionally b
37040 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c e ORed with [SQL
37050 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 ITE_DETERMINISTI
37060 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 C].** to signal
37070 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f that the functio
37080 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 n will always re
37090 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 turn the same re
370a0 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 sult given.** th
370b0 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 e same inputs wi
370c0 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 thin a single SQ
370d0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f L statement. Mo
370e0 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 st SQL functions
370f0 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e are.** determin
37100 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c istic. The buil
37110 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 t-in [random()]
37120 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 SQL function is
37130 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a an example of a.
37140 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 ** function that
37150 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e is not determin
37160 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 istic. The SQLi
37170 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 te query planner
37180 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 is able to.** p
37190 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 erform additiona
371a0 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 l optimizations
371b0 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 on deterministic
371c0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 functions, so u
371d0 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 se.** of the [SQ
371e0 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 LITE_DETERMINIST
371f0 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f IC] flag is reco
37200 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f mmended where po
37210 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ssible..**.** ^(
37220 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 The fifth parame
37230 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 ter is an arbitr
37240 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 ary pointer. Th
37250 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
37260 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 of the.** funct
37270 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 ion can gain acc
37280 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e ess to this poin
37290 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ter using [sqlit
372a0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e e3_user_data()].
372b0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 )^.**.** ^The si
372c0 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 xth, seventh and
372d0 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 eighth paramete
372e0 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 rs, xFunc, xStep
372f0 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 and xFinal, are
37300 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 .** pointers to
37310 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 C-language funct
37320 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d ions that implem
37330 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 ent the SQL func
37340 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
37350 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 gate. ^A scalar
37360 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 SQL function req
37370 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 uires an impleme
37380 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 ntation of the x
37390 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b Func.** callback
373a0 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e only; NULL poin
373b0 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 ters must be pas
373c0 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 sed as the xStep
373d0 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 and xFinal.** p
373e0 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 arameters. ^An a
373f0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e ggregate SQL fun
37400 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 ction requires a
37410 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
37420 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 of xStep.** and
37430 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c xFinal and NULL
37440 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 pointer must be
37450 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e passed for xFun
37460 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e c. ^To delete an
37470 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c existing.** SQL
37480 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 function or agg
37490 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c regate, pass NUL
374a0 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 L pointers for a
374b0 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f ll three functio
374c0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a n.** callbacks..
374d0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e **.** ^(If the n
374e0 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 inth parameter t
374f0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 o sqlite3_create
37500 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 _function_v2() i
37510 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 s not NULL,.** t
37520 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 hen it is destru
37530 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 ctor for the app
37540 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f lication data po
37550 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 inter. .** The d
37560 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 estructor is inv
37570 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 oked when the fu
37580 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 nction is delete
37590 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 d, either by bei
375a0 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 ng.** overloaded
375b0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 or when the dat
375c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
375d0 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 closes.)^.** ^T
375e0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 he destructor is
375f0 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 also invoked if
37600 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 the call to.**
37610 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
37620 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 unction_v2() fai
37630 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 ls..** ^When the
37640 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c destructor call
37650 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 back of the tent
37660 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 h parameter is i
37670 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 nvoked, it.** is
37680 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 passed a single
37690 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
376a0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
376b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
376c0 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 a .** pointer wh
376d0 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 ich was the fift
376e0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
376f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
37700 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a nction_v2()..**.
37710 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 ** ^It is permit
37720 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 ted to register
37730 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 multiple impleme
37740 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ntations of the
37750 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e same.** function
37760 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 s with the same
37770 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 name but with ei
37780 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e ther differing n
37790 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 umbers of.** arg
377a0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 uments or differ
377b0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 ing preferred te
377c0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e xt encodings. ^
377d0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a SQLite will use.
377e0 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 ** the implement
377f0 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 ation that most
37800 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 closely matches
37810 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 the way in which
37820 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 the.** SQL func
37830 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e tion is used. ^
37840 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 A function imple
37850 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 mentation with a
37860 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a non-negative.**
37870 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 nArg parameter
37880 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 is a better matc
37890 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
378a0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
378b0 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 with.** a negat
378c0 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 ive nArg. ^A fu
378d0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
378e0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 preferred text
378f0 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 encoding.** matc
37900 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 hes the database
37910 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 encoding is a b
37920 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 etter.** match t
37930 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 han a function w
37940 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e here the encodin
37950 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 g is different.
37960 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e .** ^A function
37970 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 where the encod
37980 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 ing difference i
37990 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c s between UTF16l
379a0 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a e and UTF16be.**
379b0 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 is a closer mat
379c0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 ch than a functi
379d0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 on where the enc
379e0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 oding difference
379f0 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 is.** between U
37a00 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a TF8 and UTF16..*
37a10 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 *.** ^Built-in f
37a20 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 unctions may be
37a30 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 overloaded by ne
37a40 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 w application-de
37a50 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e fined functions.
37a60 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 .**.** ^An appli
37a70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
37a80 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 unction is permi
37a90 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 tted to call oth
37aa0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 er.** SQLite int
37ab0 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 erfaces. Howeve
37ac0 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 r, such calls mu
37ad0 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 st not.** close
37ae0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
37af0 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 nection nor fina
37b00 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 lize or reset th
37b10 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 e prepared.** st
37b20 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 atement in which
37b30 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 the function is
37b40 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 running..*/.int
37b50 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
37b60 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 function(. sqli
37b70 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 te3 *db,. const
37b80 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e char *zFunction
37b90 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 Name,. int nArg
37ba0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 ,. int eTextRep
37bb0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a ,. void *pApp,.
37bc0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 void (*xFunc)(
37bd0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
37be0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
37bf0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
37c00 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 xStep)(sqlite3_c
37c10 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
37c20 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
37c30 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 void (*xFinal)(s
37c40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
37c50 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
37c60 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
37c70 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 6(. sqlite3 *db
37c80 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a ,. const void *
37c90 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 zFunctionName,.
37ca0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 int nArg,. int
37cb0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 eTextRep,. voi
37cc0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 d *pApp,. void
37cd0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 (*xFunc)(sqlite3
37ce0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
37cf0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
37d00 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 void (*xStep)(
37d10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
37d20 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
37d30 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
37d40 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f xFinal)(sqlite3_
37d50 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 context*).);.int
37d60 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
37d70 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 function_v2(. s
37d80 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f qlite3 *db,. co
37d90 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 nst char *zFunct
37da0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e ionName,. int n
37db0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 Arg,. int eText
37dc0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 Rep,. void *pAp
37dd0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e p,. void (*xFun
37de0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 c)(sqlite3_conte
37df0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
37e00 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
37e10 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 (*xStep)(sqlite
37e20 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
37e30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
37e40 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c . void (*xFinal
37e50 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
37e60 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 t*),. void(*xDe
37e70 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b stroy)(void*).);
37e80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
37e90 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 : Text Encodings
37ea0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
37eb0 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 stant define int
37ec0 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 eger codes that
37ed0 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 represent the va
37ee0 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e rious.** text en
37ef0 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 codings supporte
37f00 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a d by SQLite..*/.
37f10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
37f20 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20 TF8 1
37f30 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 /* IMP: R-375
37f40 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 14-35566 */.#def
37f50 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
37f60 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f LE 2 /
37f70 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 * IMP: R-03371-3
37f80 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 7637 */.#define
37f90 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 SQLITE_UTF16BE
37fa0 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 3 /* IM
37fb0 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 P: R-51971-34154
37fc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
37fd0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 TE_UTF16
37fe0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 4 /* Use na
37ff0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
38000 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
38010 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 E_ANY
38020 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 5 /* Depreca
38030 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ted */.#define S
38040 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 QLITE_UTF16_ALIG
38050 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c NED 8 /* sql
38060 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
38070 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f ation only */../
38080 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
38090 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a unction Flags.**
380a0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
380b0 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 nts may be ORed
380c0 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68 together with th
380d0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 e .** [SQLITE_UT
380e0 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 F8 | preferred t
380f0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 ext encoding] as
38100 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 the fourth argu
38110 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 ment.** to [sqli
38120 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
38130 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 ion()], [sqlite3
38140 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
38150 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 16()], or.** [sq
38160 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
38170 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a ction_v2()]..*/.
38180 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
38190 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 ETERMINISTIC
381a0 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 0x800../*.** CAP
381b0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 I3REF: Deprecate
381c0 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 d Functions.** D
381d0 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 EPRECATED.**.**
381e0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
381f0 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d are [deprecated]
38200 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d . In order to m
38210 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 aintain.** backw
38220 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
38230 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f ty with older co
38240 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 de, these functi
38250 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a ons continue .**
38260 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
38270 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 . However, new
38280 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f applications sho
38290 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 uld avoid.** the
382a0 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 use of these fu
382b0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 nctions. To enc
382c0 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 ourage programme
382d0 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 rs to avoid.** t
382e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 hese functions,
382f0 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c we will not expl
38300 61 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f ain what they do
38310 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c ..*/.#ifndef SQL
38320 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 ITE_OMIT_DEPRECA
38330 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 TED.SQLITE_DEPRE
38340 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
38350 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 3_aggregate_coun
38360 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
38370 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 t*);.SQLITE_DEPR
38380 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
38390 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 e3_expired(sqlit
383a0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 e3_stmt*);.SQLIT
383b0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
383c0 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 sqlite3_transfe
383d0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
383e0 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 e3_stmt*, sqlite
383f0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 3_stmt*);.SQLITE
38400 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
38410 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 sqlite3_global_r
38420 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 ecover(void);.SQ
38430 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
38440 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 void sqlite3_thr
38450 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 ead_cleanup(void
38460 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 );.SQLITE_DEPREC
38470 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 ATED int sqlite3
38480 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f _memory_alarm(vo
38490 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
384a0 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a te3_int64,int),.
384b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
384c0 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 void*,sqli
384d0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 te3_int64);.#end
384e0 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 if../*.** CAPI3R
384f0 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 EF: Obtaining SQ
38500 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 L Values.** METH
38510 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 OD: sqlite3_valu
38520 65 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 e.**.** <b>Summa
38530 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 ry:</b>.** <bloc
38540 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f kquote><table bo
38550 72 64 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 rder=0 cellpaddi
38560 6e 67 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 ng=0 cellspacing
38570 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c =0>.** <tr><td><
38580 62 3e 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f b>sqlite3_value_
38590 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 blob</b><td>&rar
385a0 72 3b 3c 74 64 3e 42 4c 4f 42 20 76 61 6c 75 65 r;<td>BLOB value
385b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 .** <tr><td><b>s
385c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 qlite3_value_dou
385d0 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 ble</b><td>&rarr
385e0 3b 3c 74 64 3e 52 45 41 4c 20 76 61 6c 75 65 0a ;<td>REAL value.
385f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 ** <tr><td><b>sq
38600 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 3c lite3_value_int<
38610 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 /b><td>→<td
38620 3e 33 32 2d 62 69 74 20 49 4e 54 45 47 45 52 20 >32-bit INTEGER
38630 76 61 6c 75 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 value.** <tr><td
38640 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 76 61 6c 75 ><b>sqlite3_valu
38650 65 5f 69 6e 74 36 34 3c 2f 62 3e 3c 74 64 3e 26 e_int64</b><td>&
38660 72 61 72 72 3b 3c 74 64 3e 36 34 2d 62 69 74 20 rarr;<td>64-bit
38670 49 4e 54 45 47 45 52 20 76 61 6c 75 65 0a 2a 2a INTEGER value.**
38680 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 <tr><td><b>sqli
38690 74 65 33 5f 76 61 6c 75 65 5f 70 6f 69 6e 74 65 te3_value_pointe
386a0 72 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c r</b><td>→<
386b0 74 64 3e 50 6f 69 6e 74 65 72 20 76 61 6c 75 65 td>Pointer value
386c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 .** <tr><td><b>s
386d0 71 6c 69 74 65 33 5f 7