0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35 /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 urce code. In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 al notice, here
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 *.** May you
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 do good and not
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 evil..** May
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65 you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 hers..** May
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79 you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76 ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66 ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20 ile defines the
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74 interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73 client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69 . If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64 on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69 onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41 ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73 PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64 tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63 not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74 ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68 e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66 at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61 ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74 s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74 al". Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 ite. We do not
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67 anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65 but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 inor changes.**
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63 ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 e is derived.**
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 this file. Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66 e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 file makes some
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68 this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73 ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64 art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23 ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48 define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72 .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64 g.h> /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74 ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 */../*.** Make
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 C++..*/.#ifdef
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65 __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20 ../*.** Provide
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20 verride linkage
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20 features of the
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69 interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54 fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72 ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65 QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43 fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54 ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53 DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51 QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65 TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50 def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72 nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20 faces as either
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78 deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 perimental. New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 should not use
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72 deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65 faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 atibility only.
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61 ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74 aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69 d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67 ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61 that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 nd gone back to
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 using simple.**
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 le-Time Library
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70 ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61 .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69 luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 ng literal that
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 rsion in the.**
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77 format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61 here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72 er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64 .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 Y is the minor
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65 nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 cro resolves to
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69 an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59 + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20 , and Z are the
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 same.** numbers
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79 N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20 so.** be larger
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65 than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69 from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68 s derived. Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 er Y will.** be
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20 emented or else
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20 ill be reset to
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65 18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73 source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 been stored in
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 ystem</a>. ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65 D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65 which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20 e.** within its
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 ate and time of
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73 or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 h of the entire
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66 source tree. If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65 the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69 has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73 ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74 ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65 checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73 igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65 h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 LITE_VERSION
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d OURCE_ID "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 un-Time Library
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 TE_SOURCE_ID] C
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f file. ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 s might include
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 atch the macros
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72 , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 ing library and
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65 ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30 ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 ins the text of
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 .** macro. ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ant. The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 tring constants
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 within the DLL.
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c BER]. ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 ite3_sourceid()
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 ant whose value
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20 rocessor macro.
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74 Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73 e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67 py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74 amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61 he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68 racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20 e hash might be
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61 void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 on returns 0 or
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 compile time.
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 ed from the .**
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 (). .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 ined at compile
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e n string. ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 pointer. ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 tion at compile
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 time..**.** See
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69 pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6c 73 65 0a 23 20 64 nt N);.#else.# d
1e00: 65 66 69 6e 65 20 73 71 6c 69 74 65 33 5f 63 6f efine sqlite3_co
1e10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 mpileoption_used
1e20: 28 58 29 20 30 0a 23 20 64 65 66 69 6e 65 20 73 (X) 0.# define s
1e30: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
1e40: 74 69 6f 6e 5f 67 65 74 28 58 29 20 20 28 28 76 tion_get(X) ((v
1e50: 6f 69 64 2a 29 30 29 0a 23 65 6e 64 69 66 0a 0a oid*)0).#endif..
1e60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1e70: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 Test To See If T
1e80: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 he Library Is Th
1e90: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e readsafe.**.** ^
1ea0: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 The sqlite3_thre
1eb0: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f adsafe() functio
1ec0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 n returns zero i
1ed0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a f and only if.**
1ee0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 SQLite was comp
1ef0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 iled with mutexi
1f00: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 ng code omitted
1f10: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 due to the.** [S
1f20: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1f30: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
1f40: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 ption being set
1f50: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 to 0..**.** SQLi
1f60: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c te can be compil
1f70: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f ed with or witho
1f80: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 ut mutexes. Whe
1f90: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 n.** the [SQLITE
1fa0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 _THREADSAFE] C p
1fb0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
1fc0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 o is 1 or 2, mut
1fd0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 exes.** are enab
1fe0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 led and SQLite i
1ff0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 s threadsafe. W
2000: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 hen the.** [SQLI
2010: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d TE_THREADSAFE] m
2020: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 acro is 0, .** t
2030: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f he mutexes are o
2040: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 mitted. Without
2050: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 the mutexes, it
2060: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 is not safe.**
2070: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f to use SQLite co
2080: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 ncurrently from
2090: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 more than one th
20a0: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 read..**.** Enab
20b0: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 ling mutexes inc
20c0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 urs a measurable
20d0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e performance pen
20e0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 alty..** So if s
20f0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 peed is of utmos
2100: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 t importance, it
2110: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 makes sense to
2120: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d disable.** the m
2130: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 utexes. But for
2140: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c maximum safety,
2150: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 mutexes should
2160: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e be enabled..** ^
2170: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 The default beha
2180: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 vior is for mute
2190: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 xes to be enable
21a0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e d..**.** This in
21b0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
21c0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 sed by an applic
21d0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 ation to make su
21e0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 re that the.** v
21f0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 ersion of SQLite
2200: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b that it is link
2210: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 ing against was
2220: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
2230: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 the desired set
2240: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c ting of the [SQL
2250: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
2260: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 macro..**.** Thi
2270: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 s interface only
2280: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 reports on the
2290: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 compile-time mut
22a0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 ex setting.** of
22b0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
22c0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 EADSAFE] flag.
22d0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
22e0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 piled with.** SQ
22f0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
2300: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 1 or =2 then mut
2310: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 exes are enabled
2320: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a by default but.
2330: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 ** can be fully
2340: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 or partially dis
2350: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 abled using a ca
2360: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
2370: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 onfig()].** with
2380: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 the verbs [SQLI
2390: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
23a0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 THREAD], [SQLITE
23b0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
23c0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c EAD],.** or [SQL
23d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
23e0: 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 LIZED]. ^(The r
23f0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
2400: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 he.** sqlite3_th
2410: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 readsafe() funct
2420: 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 ion shows only t
2430: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 he compile-time
2440: 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 setting of.** th
2450: 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 read safety, not
2460: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 any run-time ch
2470: 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 anges to that se
2480: 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a tting made by.**
2490: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
24a0: 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 ). In other word
24b0: 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 s, the return va
24c0: 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
24d0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a _threadsafe().**
24e0: 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 is unchanged by
24f0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
2500: 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 3_config().)^.**
2510: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 .** See the [thr
2520: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 eading mode] doc
2530: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 umentation for a
2540: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
2550: 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ation..*/.int sq
2560: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
2570: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 (void);../*.** C
2580: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 API3REF: Databas
2590: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e e Connection Han
25a0: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a dle.** KEYWORDS:
25b0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 {database conne
25c0: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 ction} {database
25d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a connections}.**
25e0: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 .** Each open SQ
25f0: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 Lite database is
2600: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
2610: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
2620: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 instance of.** t
2630: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 he opaque struct
2640: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 ure named "sqlit
2650: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 e3". It is usef
2660: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 ul to think of a
2670: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 n sqlite3.** poi
2680: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 nter as an objec
2690: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 t. The [sqlite3
26a0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
26b0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e e3_open16()], an
26c0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 d.** [sqlite3_op
26d0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
26e0: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 ces are its cons
26f0: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 tructors, and [s
2700: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a qlite3_close()].
2710: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
2720: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 close_v2()] are
2730: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e its destructors.
2740: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 There are many
2750: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 other.** interf
2760: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a aces (such as.**
2770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 e_v2()], [sqlite
2790: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
27a0: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 n()], and.** [sq
27b0: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
27c0: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 ut()] to name bu
27d0: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 t three) that ar
27e0: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a e methods on an.
27f0: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 ** sqlite3 objec
2800: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 t..*/.typedef st
2810: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c ruct sqlite3 sql
2820: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ite3;../*.** CAP
2830: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e I3REF: 64-Bit In
2840: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b teger Types.** K
2850: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f EYWORDS: sqlite_
2860: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e int64 sqlite_uin
2870: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 t64.**.** Becaus
2880: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 e there is no cr
2890: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 oss-platform way
28a0: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 to specify 64-b
28b0: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 it integer types
28c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 .** SQLite inclu
28d0: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 des typedefs for
28e0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 64-bit signed a
28f0: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 nd unsigned inte
2900: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 gers..**.** The
2910: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e sqlite3_int64 an
2920: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 d sqlite3_uint64
2930: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 are the preferr
2940: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 ed type definiti
2950: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ons..** The sqli
2960: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c te_int64 and sql
2970: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 ite_uint64 types
2980: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 are supported f
2990: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 or backwards.**
29a0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e compatibility on
29b0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ly..**.** ^The s
29c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 qlite3_int64 and
29d0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 sqlite_int64 ty
29e0: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e pes can store in
29f0: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 teger values.**
2a00: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 between -9223372
2a10: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 036854775808 and
2a20: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 +92233720368547
2a30: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 75807 inclusive.
2a40: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 ^The.** sqlite
2a50: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 3_uint64 and sql
2a60: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 ite_uint64 types
2a70: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 can store integ
2a80: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 er values .** be
2a90: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 tween 0 and +184
2aa0: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 4674407370955161
2ab0: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 5 inclusive..*/.
2ac0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e #ifdef SQLITE_IN
2ad0: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 T64_TYPE. typed
2ae0: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f ef SQLITE_INT64_
2af0: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 TYPE sqlite_int6
2b00: 34 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 4;.# ifdef SQLIT
2b10: 45 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 E_UINT64_TYPE.
2b20: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 typedef SQLITE
2b30: 5f 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c _UINT64_TYPE sql
2b40: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c ite_uint64;.# el
2b50: 73 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 se . typedef
2b60: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 unsigned SQLITE
2b70: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 _INT64_TYPE sqli
2b80: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 te_uint64;.# end
2b90: 69 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 if.#elif defined
2ba0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 (_MSC_VER) || de
2bb0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 fined(__BORLANDC
2bc0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f __). typedef __
2bd0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 int64 sqlite_int
2be0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 64;. typedef un
2bf0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 signed __int64 s
2c00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 qlite_uint64;.#e
2c10: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f lse. typedef lo
2c20: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 ng long int sqli
2c30: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 te_int64;. type
2c40: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e def unsigned lon
2c50: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 g long int sqlit
2c60: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 e_uint64;.#endif
2c70: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f .typedef sqlite_
2c80: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e int64 sqlite3_in
2c90: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c t64;.typedef sql
2ca0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 ite_uint64 sqlit
2cb0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a e3_uint64;../*.*
2cc0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 * If compiling f
2cd0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 or a processor t
2ce0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 hat lacks floati
2cf0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 ng point support
2d00: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 ,.** substitute
2d10: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 integer for floa
2d20: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 ting-point..*/.#
2d30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 ifdef SQLITE_OMI
2d40: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 T_FLOATING_POINT
2d50: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 .# define double
2d60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 sqlite3_int64.#
2d70: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 endif../*.** CAP
2d80: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 I3REF: Closing A
2d90: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
2da0: 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 tion.** DESTRUCT
2db0: 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OR: sqlite3.**.*
2dc0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
2dd0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 lose() and sqlit
2de0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f e3_close_v2() ro
2df0: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 utines are destr
2e00: 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 uctors.** for th
2e10: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 e [sqlite3] obje
2e20: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f ct..** ^Calls to
2e30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 sqlite3_close()
2e40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f and sqlite3_clo
2e50: 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b se_v2() return [
2e60: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a SQLITE_OK] if.**
2e70: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
2e80: 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 bject is success
2e90: 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 fully destroyed
2ea0: 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 and all associat
2eb0: 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 ed.** resources
2ec0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e are deallocated.
2ed0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 .**.** ^If the d
2ee0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2ef0: 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 on is associated
2f00: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 with unfinalize
2f10: 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 d prepared.** st
2f20: 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 atements or unfi
2f30: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 nished sqlite3_b
2f40: 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 ackup objects th
2f50: 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 en sqlite3_close
2f60: 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 ().** will leave
2f70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
2f80: 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e nnection open an
2f90: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 d return [SQLITE
2fa0: 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 _BUSY]..** ^If s
2fb0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 qlite3_close_v2(
2fc0: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 ) is called with
2fd0: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 unfinalized pre
2fe0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
2ff0: 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e .** and/or unfin
3000: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 ished sqlite3_ba
3010: 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 ckups, then the
3020: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3030: 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 ion becomes.** a
3040: 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 n unusable "zomb
3050: 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 ie" which will a
3060: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 utomatically be
3070: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e deallocated when
3080: 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 the.** last pre
3090: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
30a0: 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 is finalized or
30b0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 the last sqlite3
30c0: 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 _backup is.** fi
30d0: 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c nished. The sql
30e0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 ite3_close_v2()
30f0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 interface is int
3100: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 ended for use wi
3110: 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 th.** host langu
3120: 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 ages that are ga
3130: 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c rbage collected,
3140: 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f and where the o
3150: 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a rder in which.**
3160: 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 destructors are
3170: 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 called is arbit
3180: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c rary..**.** Appl
3190: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ications should
31a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
31b0: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c e | finalize] al
31c0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 l [prepared stat
31d0: 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c ements],.** [sql
31e0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 ite3_blob_close
31f0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c | close] all [BL
3200: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 OB handles], and
3210: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 .** [sqlite3_ba
3220: 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 ckup_finish | fi
3230: 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 nish] all [sqlit
3240: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 e3_backup] objec
3250: 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a ts associated.**
3260: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 with the [sqlit
3270: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 e3] object prior
3280: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 to attempting t
3290: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 o close the obje
32a0: 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 ct. ^If.** sqli
32b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 te3_close_v2() i
32c0: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 s called on a [d
32d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
32e0: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 on] that still h
32f0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e as.** outstandin
3300: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 g [prepared stat
3310: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 ements], [BLOB h
3320: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a andles], and/or.
3330: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b ** [sqlite3_back
3340: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e up] objects then
3350: 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c it returns [SQL
3360: 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 ITE_OK] and the
3370: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 deallocation.**
3380: 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 of resources is
3390: 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 deferred until a
33a0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ll [prepared sta
33b0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 tements], [BLOB
33c0: 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 handles],.** and
33d0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 [sqlite3_backup
33e0: 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c ] objects are al
33f0: 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a so destroyed..**
3400: 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 .** ^If an [sqli
3410: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 te3] object is d
3420: 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 estroyed while a
3430: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
3440: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 open,.** the tra
3450: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f nsaction is auto
3460: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 matically rolled
3470: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 back..**.** The
3480: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 C parameter to
3490: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 [sqlite3_close(C
34a0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
34b0: 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 close_v2(C)].**
34c0: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 must be either a
34d0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 NULL.** pointer
34e0: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d or an [sqlite3]
34f0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 object pointer
3500: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d obtained.** from
3510: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
3520: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
3530: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 16()], or.** [sq
3540: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
3550: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f , and not previo
3560: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 usly closed..**
3570: 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 ^Calling sqlite3
3580: 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 _close() or sqli
3590: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 te3_close_v2() w
35a0: 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
35b0: 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 er.** argument i
35c0: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d s a harmless no-
35d0: 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 op..*/.int sqlit
35e0: 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 e3_close(sqlite3
35f0: 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
3600: 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 close_v2(sqlite3
3610: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 *);../*.** The t
3620: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 ype for a callba
3630: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 ck function..**
3640: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 This is legacy a
3650: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 nd deprecated.
3660: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 It is included f
3670: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a or historical.**
3680: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 compatibility a
3690: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 nd is not docume
36a0: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 nted..*/.typedef
36b0: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 int (*sqlite3_c
36c0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 allback)(void*,i
36d0: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a nt,char**, char*
36e0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
36f0: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 REF: One-Step Qu
3700: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e ery Execution In
3710: 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f terface.** METHO
3720: 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
3730: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 The sqlite3_exe
3740: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 c() interface is
3750: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 a convenience w
3760: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a rapper around.**
3770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
3780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 e_v2()], [sqlite
3790: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 3_step()], and [
37a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
37b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c ()],.** that all
37c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 ows an applicati
37d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 on to run multip
37e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 le statements of
37f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 SQL.** without
3800: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 having to use a
3810: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a lot of C code. .
3820: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
3830: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 e3_exec() interf
3840: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 ace runs zero or
3850: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f more UTF-8 enco
3860: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f ded,.** semicolo
3870: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 n-separate SQL s
3880: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 tatements passed
3890: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 into its 2nd ar
38a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 gument,.** in th
38b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 e context of the
38c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
38d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e ction] passed in
38e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 as its 1st.** a
38f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 rgument. ^If th
3900: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
3910: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 ion of the 3rd a
3920: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 rgument to.** sq
3930: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
3940: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 not NULL, then i
3950: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 t is invoked for
3960: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 each result row
3970: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f .** coming out o
3980: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 f the evaluated
3990: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 SQL statements.
39a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 ^The 4th argume
39b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 nt to.** sqlite3
39c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 _exec() is relay
39d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 ed through to th
39e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f e 1st argument o
39f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 f each.** callba
3a00: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 ck invocation.
3a10: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ^If the callback
3a20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 pointer to sqli
3a30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 te3_exec().** is
3a40: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 NULL, then no c
3a50: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 allback is ever
3a60: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 invoked and resu
3a70: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 lt rows are.** i
3a80: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 gnored..**.** ^I
3a90: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 f an error occur
3aa0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 s while evaluati
3ab0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 ng the SQL state
3ac0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 ments passed int
3ad0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 o.** sqlite3_exe
3ae0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 c(), then execut
3af0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 ion of the curre
3b00: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f nt statement sto
3b10: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 ps and.** subseq
3b20: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 uent statements
3b30: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 are skipped. ^I
3b40: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 f the 5th parame
3b50: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
3b60: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 xec().** is not
3b70: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 NULL then any er
3b80: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 ror message is w
3b90: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f ritten into memo
3ba0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 ry obtained.** f
3bb0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
3bc0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 loc()] and passe
3bd0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 d back through t
3be0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
3bf0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 ..** To avoid me
3c00: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 mory leaks, the
3c10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
3c20: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 ld invoke [sqlit
3c30: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e e3_free()].** on
3c40: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
3c50: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 trings returned
3c60: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 through the 5th
3c70: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 parameter of.**
3c80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 sqlite3_exec() a
3c90: 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d fter the error m
3ca0: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 essage string is
3cb0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 no longer neede
3cc0: 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 d..** ^If the 5t
3cd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
3ce0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 qlite3_exec() is
3cf0: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f not NULL and no
3d00: 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 errors.** occur
3d10: 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 , then sqlite3_e
3d20: 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 xec() sets the p
3d30: 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 ointer in its 5t
3d40: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a h parameter to.*
3d50: 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 * NULL before re
3d60: 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e turning..**.** ^
3d70: 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 If an sqlite3_ex
3d80: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 ec() callback re
3d90: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
3da0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 the sqlite3_exec
3db0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 ().** routine re
3dc0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f turns SQLITE_ABO
3dd0: 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b RT without invok
3de0: 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ing the callback
3df0: 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 again and.** wi
3e00: 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e thout running an
3e10: 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c y subsequent SQL
3e20: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a statements..**.
3e30: 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 ** ^The 2nd argu
3e40: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 ment to the sqli
3e50: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 te3_exec() callb
3e60: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ack function is
3e70: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
3e80: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
3e90: 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 result. ^The 3r
3ea0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 d argument to th
3eb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
3ec0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 .** callback is
3ed0: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e an array of poin
3ee0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 ters to strings
3ef0: 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 obtained as if f
3f00: 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f rom.** [sqlite3_
3f10: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 column_text()],
3f20: 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c one for each col
3f30: 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 umn. ^If an ele
3f40: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 ment of a.** res
3f50: 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 ult row is NULL
3f60: 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 then the corresp
3f70: 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f onding string po
3f80: 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a inter for the.**
3f90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3fa0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 callback is a NU
3fb0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 LL pointer. ^Th
3fc0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 e 4th argument t
3fd0: 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 o the.** sqlite3
3fe0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b _exec() callback
3ff0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 is an array of
4000: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 pointers to stri
4010: 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a ngs where each.*
4020: 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e * entry represen
4030: 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 ts the name of c
4040: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 orresponding res
4050: 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 ult column as ob
4060: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b tained.** from [
4070: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
4080: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 ame()]..**.** ^I
4090: 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 f the 2nd parame
40a0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
40b0: 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 xec() is a NULL
40c0: 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 pointer, a point
40d0: 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 er.** to an empt
40e0: 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 y string, or a p
40f0: 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 ointer that cont
4100: 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 ains only whites
4110: 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 pace and/or .**
4120: 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 SQL comments, th
4130: 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d en no SQL statem
4140: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 ents are evaluat
4150: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 ed and the datab
4160: 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 ase.** is not ch
4170: 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 anged..**.** Res
4180: 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a trictions:.**.**
4190: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 <ul>.** <li> Th
41a0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
41b0: 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 st ensure that t
41c0: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 he 1st parameter
41d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 to sqlite3_exec
41e0: 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 ().** is a
41f0: 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b valid and open [
4200: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
4210: 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 ion]..** <li> Th
4220: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
4230: 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 st not close the
4240: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
4250: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 ction] specified
4260: 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 by.** the
4270: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 1st parameter to
4280: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
4290: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 while sqlite3_ex
42a0: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e ec() is running.
42b0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 .** <li> The app
42c0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f lication must no
42d0: 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c t modify the SQL
42e0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 statement text
42f0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 passed into.**
4300: 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 the 2nd para
4310: 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 meter of sqlite3
4320: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 _exec() while sq
4330: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
4340: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c running..** </ul
4350: 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 >.*/.int sqlite3
4360: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 _exec(. sqlite3
4370: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *,
4380: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4390: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 /* An open d
43a0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e atabase */. con
43b0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 st char *sql,
43c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
43d0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 /* SQL t
43e0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a o be evaluated *
43f0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 /. int (*callba
4400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 ck)(void*,int,ch
4410: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f ar**,char**), /
4420: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * Callback funct
4430: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c ion */. void *,
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4450: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4460: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d /* 1st argum
4470: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 ent to callback
4480: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d */. char **errm
4490: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 sg
44a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
44b0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 /* Error msg wri
44c0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a tten here */.);.
44d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
44e0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a Result Codes.**
44f0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 KEYWORDS: {resu
4500: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 lt code definiti
4510: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 ons}.**.** Many
4520: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 SQLite functions
4530: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 return an integ
4540: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 er result code f
4550: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 rom the set show
4560: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 n.** here in ord
4570: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 er to indicate s
4580: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 uccess or failur
4590: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 e..**.** New err
45a0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 or codes may be
45b0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
45c0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
45d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c te..**.** See al
45e0: 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 so: [extended re
45f0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 sult code defini
4600: 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e tions].*/.#defin
4610: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 e SQLITE_OK
4620: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 0 /* Suc
4630: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a cessful result *
4640: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f /./* beginning-o
4650: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f f-error-codes */
4660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4670: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 ERROR 1
4680: 20 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f /* Generic erro
4690: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
46a0: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 ITE_INTERNAL
46b0: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 2 /* Internal
46c0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 logic error in
46d0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e SQLite */.#defin
46e0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 e SQLITE_PERM
46f0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 3 /* Acc
4700: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 ess permission d
4710: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 enied */.#define
4720: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 SQLITE_ABORT
4730: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 4 /* Call
4740: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 back routine req
4750: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 uested an abort
4760: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4770: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 E_BUSY 5
4780: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 /* The databa
4790: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 se file is locke
47a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
47b0: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 ITE_LOCKED
47c0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 6 /* A table
47d0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 in the database
47e0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 is locked */.#de
47f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 fine SQLITE_NOME
4800: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 M 7 /*
4810: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 A malloc() faile
4820: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4830: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 ITE_READONLY
4840: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 8 /* Attempt
4850: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f to write a reado
4860: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a nly database */.
4870: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4880: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 NTERRUPT 9
4890: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 /* Operation ter
48a0: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 minated by sqlit
48b0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f e3_interrupt()*/
48c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
48d0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 IOERR 10
48e0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 /* Some kind of
48f0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 disk I/O error
4900: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 occurred */.#def
4910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 ine SQLITE_CORRU
4920: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 PT 11 /* T
4930: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b he database disk
4940: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 image is malfor
4950: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 med */.#define S
4960: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 QLITE_NOTFOUND
4970: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 12 /* Unknow
4980: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 n opcode in sqli
4990: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
49a0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
49b0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 LITE_FULL
49c0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 13 /* Inserti
49d0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 on failed becaus
49e0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 e database is fu
49f0: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ll */.#define SQ
4a00: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 LITE_CANTOPEN
4a10: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 14 /* Unable
4a20: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 to open the data
4a30: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 base file */.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 fine SQLITE_PROT
4a50: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 OCOL 15 /*
4a60: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 Database lock pr
4a70: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a otocol error */.
4a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 #define SQLITE_E
4a90: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 MPTY 16
4aa0: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 /* Internal use
4ab0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
4ac0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 SQLITE_SCHEMA
4ad0: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 17 /* The d
4ae0: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 atabase schema c
4af0: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e hanged */.#defin
4b00: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 e SQLITE_TOOBIG
4b10: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 18 /* Str
4b20: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 ing or BLOB exce
4b30: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a eds size limit *
4b40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4b50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 _CONSTRAINT 19
4b60: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 /* Abort due t
4b70: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f o constraint vio
4b80: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e lation */.#defin
4b90: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 e SQLITE_MISMATC
4ba0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 H 20 /* Dat
4bb0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 a type mismatch
4bc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4bd0: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 E_MISUSE 21
4be0: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 /* Library us
4bf0: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a ed incorrectly *
4c00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4c10: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 _NOLFS 22
4c20: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 /* Uses OS fea
4c30: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 tures not suppor
4c40: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 ted on host */.#
4c50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 define SQLITE_AU
4c60: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f TH 23 /
4c70: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 * Authorization
4c80: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e denied */.#defin
4c90: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 e SQLITE_FORMAT
4ca0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 24 /* Not
4cb0: 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 used */.#define
4cc0: 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 SQLITE_RANGE
4cd0: 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 25 /* 2nd
4ce0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
4cf0: 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 ite3_bind out of
4d00: 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e range */.#defin
4d10: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 e SQLITE_NOTADB
4d20: 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 26 /* Fil
4d30: 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 e opened that is
4d40: 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 not a database
4d50: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 file */.#define
4d60: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 SQLITE_NOTICE
4d70: 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 27 /* Notif
4d80: 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 ications from sq
4d90: 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 lite3_log() */.#
4da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 define SQLITE_WA
4db0: 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f RNING 28 /
4dc0: 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 * Warnings from
4dd0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f sqlite3_log() */
4de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4df0: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 ROW 100
4e00: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 /* sqlite3_step
4e10: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 () has another r
4e20: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 ow ready */.#def
4e30: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 ine SQLITE_DONE
4e40: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 101 /* s
4e50: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 qlite3_step() ha
4e60: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 s finished execu
4e70: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f ting */./* end-o
4e80: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f f-error-codes */
4e90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
4ea0: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c : Extended Resul
4eb0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f t Codes.** KEYWO
4ec0: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 RDS: {extended r
4ed0: 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e esult code defin
4ee0: 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e itions}.**.** In
4ef0: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e its default con
4f00: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 figuration, SQLi
4f10: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 te API routines
4f20: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 return one of 30
4f30: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 integer.** [res
4f40: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 ult codes]. How
4f50: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 ever, experience
4f60: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 has shown that
4f70: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 many of.** these
4f80: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 result codes ar
4f90: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 e too coarse-gra
4fa0: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e ined. They do n
4fb0: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a ot provide as.**
4fc0: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f much informatio
4fd0: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 n about problems
4fe0: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 as programmers
4ff0: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 might like. In
5000: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 an effort to.**
5010: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 address this, ne
5020: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 wer versions of
5030: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 SQLite (version
5040: 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 3.3.8 [dateof:3.
5050: 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 3.8].** and late
5060: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 r) include.** su
5070: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 pport for additi
5080: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 onal result code
5090: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d s that provide m
50a0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 ore detailed inf
50b0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 ormation.** abou
50c0: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 t errors. These
50d0: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
50e0: 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 codes] are enab
50f0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a led or disabled.
5100: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 ** on a per data
5110: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
5120: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a basis using the.
5130: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 ** [sqlite3_exte
5140: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
5150: 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 s()] API. Or, t
5160: 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 he extended code
5170: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 for.** the most
5180: 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 recent error ca
5190: 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 n be obtained us
51a0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
51b0: 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 extended_errcode
51c0: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ()]..*/.#define
51d0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 SQLITE_ERROR_MIS
51e0: 53 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 SING_COLLSEQ (
51f0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 SQLITE_ERROR | (
5200: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
5210: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 QLITE_ERROR_RETR
5220: 59 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 Y (S
5230: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 QLITE_ERROR | (2
5240: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5250: 4c 49 54 45 5f 45 52 52 4f 52 5f 53 4e 41 50 53 LITE_ERROR_SNAPS
5260: 48 4f 54 20 20 20 20 20 20 20 20 20 20 28 53 51 HOT (SQ
5270: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 33 3c LITE_ERROR | (3<
5280: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5290: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 ITE_IOERR_READ
52a0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
52b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c ITE_IOERR | (1<<
52c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
52d0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
52e0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 EAD (SQLI
52f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 TE_IOERR | (2<<8
5300: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5310: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 E_IOERR_WRITE
5320: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5330: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 E_IOERR | (3<<8)
5340: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5350: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 _IOERR_FSYNC
5360: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5370: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 _IOERR | (4<<8))
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5390: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 IOERR_DIR_FSYNC
53a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
53b0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a IOERR | (5<<8)).
53c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
53d0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 OERR_TRUNCATE
53e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
53f0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 OERR | (6<<8)).#
5400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5410: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 ERR_FSTAT
5420: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5430: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 ERR | (7<<8)).#d
5440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5450: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 RR_UNLOCK
5460: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5470: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 RR | (8<<8)).#de
5480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
5490: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 R_RDLOCK
54a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
54b0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 R | (9<<8)).#def
54c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
54d0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
54e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
54f0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 | (10<<8)).#def
5500: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5510: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 _BLOCKED
5520: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5530: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 | (11<<8)).#def
5540: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5550: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 _NOMEM
5560: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5570: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 | (12<<8)).#def
5580: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5590: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 _ACCESS
55a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
55b0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 | (13<<8)).#def
55c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
55d0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f _CHECKRESERVEDLO
55e0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 CK (SQLITE_IOERR
55f0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 | (14<<8)).#def
5600: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5610: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 _LOCK
5620: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5630: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 | (15<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5650: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 _CLOSE
5660: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5670: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 | (16<<8)).#def
5680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5690: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 _DIR_CLOSE
56a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
56b0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 | (17<<8)).#def
56c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
56d0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 _SHMOPEN
56e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
56f0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 | (18<<8)).#def
5700: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5710: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 _SHMSIZE
5720: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5730: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 | (19<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5750: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 _SHMLOCK
5760: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5770: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 | (20<<8)).#def
5780: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5790: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 _SHMMAP
57a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
57b0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 | (21<<8)).#def
57c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
57d0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 _SEEK
57e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
57f0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 | (22<<8)).#def
5800: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5810: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 _DELETE_NOENT
5820: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5830: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 | (23<<8)).#def
5840: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5850: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 _MMAP
5860: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5870: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 | (24<<8)).#def
5880: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5890: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 _GETTEMPPATH
58a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
58b0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 | (25<<8)).#def
58c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
58d0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 _CONVPATH
58e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
58f0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 | (26<<8)).#def
5900: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5910: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20 _VNODE
5920: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5930: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 | (27<<8)).#def
5940: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5950: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20 _AUTH
5960: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5970: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66 | (28<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5990: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20 _BEGIN_ATOMIC
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
59b0: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66 | (29<<8)).#def
59c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
59d0: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20 _COMMIT_ATOMIC
59e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
59f0: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66 | (30<<8)).#def
5a00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5a10: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 _ROLLBACK_ATOMIC
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5a30: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66 | (31<<8)).#def
5a40: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 ine SQLITE_LOCKE
5a50: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 D_SHAREDCACHE
5a60: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 (SQLITE_LOCKE
5a70: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 D | (1<<8)).#de
5a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
5a90: 45 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 ED_VTAB
5aa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b (SQLITE_LOCK
5ab0: 45 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 ED | (2<<8)).#d
5ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
5ad0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 Y_RECOVERY
5ae0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 (SQLITE_BUS
5af0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 Y | (1<<8)).#
5b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 define SQLITE_BU
5b10: 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 SY_SNAPSHOT
5b20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 (SQLITE_BU
5b30: 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a SY | (2<<8)).
5b40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5b50: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 ANTOPEN_NOTEMPDI
5b60: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 R (SQLITE_C
5b70: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 ANTOPEN | (1<<8)
5b80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5b90: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 _CANTOPEN_ISDIR
5ba0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5bb0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c _CANTOPEN | (2<<
5bc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5bd0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c TE_CANTOPEN_FULL
5be0: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 PATH (SQLI
5bf0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 TE_CANTOPEN | (3
5c00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5c10: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f LITE_CANTOPEN_CO
5c20: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 NVPATH (SQ
5c30: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 LITE_CANTOPEN |
5c40: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (4<<8)).#define
5c50: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f SQLITE_CANTOPEN_
5c60: 44 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28 DIRTYWAL (
5c70: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 SQLITE_CANTOPEN
5c80: 7c 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74 | (5<<8)) /* Not
5c90: 20 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 Used */.#define
5ca0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f SQLITE_CORRUPT_
5cb0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 VTAB
5cc0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 (SQLITE_CORRUPT
5cd0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
5ce0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 e SQLITE_CORRUPT
5cf0: 5f 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20 _SEQUENCE
5d00: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 (SQLITE_CORRUPT
5d10: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
5d20: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e ne SQLITE_READON
5d30: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 LY_RECOVERY
5d40: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e (SQLITE_READON
5d50: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 LY | (1<<8)).#de
5d60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
5d70: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 ONLY_CANTLOCK
5d80: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 (SQLITE_READ
5d90: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 ONLY | (2<<8)).#
5da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
5db0: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 ADONLY_ROLLBACK
5dc0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 (SQLITE_RE
5dd0: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 ADONLY | (3<<8))
5de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5df0: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 READONLY_DBMOVED
5e00: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5e10: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 READONLY | (4<<8
5e20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5e30: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 E_READONLY_CANTI
5e40: 4e 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54 NIT (SQLIT
5e50: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c E_READONLY | (5<
5e60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5e70: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 ITE_READONLY_DIR
5e80: 45 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c ECTORY (SQL
5e90: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 ITE_READONLY | (
5ea0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 6<<8)).#define S
5eb0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c QLITE_ABORT_ROLL
5ec0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 BACK (S
5ed0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 QLITE_ABORT | (2
5ee0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5ef0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
5f00: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 CHECK (SQ
5f10: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
5f20: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
5f30: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
5f40: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 INT_COMMITHOOK
5f50: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 (SQLITE_CONSTRA
5f60: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 INT | (2<<8)).#d
5f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
5f80: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b STRAINT_FOREIGNK
5f90: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e EY (SQLITE_CON
5fa0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 STRAINT | (3<<8)
5fb0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5fc0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 _CONSTRAINT_FUNC
5fd0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 TION (SQLITE
5fe0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 _CONSTRAINT | (4
5ff0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6000: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
6010: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 NOTNULL (SQ
6020: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
6030: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (5<<8)).#defin
6040: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
6050: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 INT_PRIMARYKEY
6060: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 (SQLITE_CONSTRA
6070: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 INT | (6<<8)).#d
6080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
6090: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 STRAINT_TRIGGER
60a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e (SQLITE_CON
60b0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 STRAINT | (7<<8)
60c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
60d0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 _CONSTRAINT_UNIQ
60e0: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 UE (SQLITE
60f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 _CONSTRAINT | (8
6100: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6110: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
6120: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 VTAB (SQ
6130: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
6140: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (9<<8)).#defin
6150: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
6160: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 INT_ROWID
6170: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 (SQLITE_CONSTRA
6180: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 INT |(10<<8)).#d
6190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 efine SQLITE_NOT
61a0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 ICE_RECOVER_WAL
61b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 (SQLITE_NOT
61c0: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 ICE | (1<<8)).#d
61d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 efine SQLITE_NOT
61e0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c ICE_RECOVER_ROLL
61f0: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 BACK (SQLITE_NOT
6200: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 ICE | (2<<8)).#d
6210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 efine SQLITE_WAR
6220: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 NING_AUTOINDEX
6230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 (SQLITE_WAR
6240: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 NING | (1<<8)).#
6250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 define SQLITE_AU
6260: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 TH_USER
6270: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 (SQLITE_AU
6280: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 TH | (1<<8)).#de
6290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c fine SQLITE_OK_L
62a0: 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 OAD_PERMANENTLY
62b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c (SQLITE_OK |
62c0: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 (1<<8))../*.**
62d0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 CAPI3REF: Flags
62e0: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 For File Open Op
62f0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 erations.**.** T
6300: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 hese bit values
6310: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 are intended for
6320: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 use in the.** 3
6330: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
6340: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 the [sqlite3_ope
6350: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 n_v2()] interfac
6360: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 e and.** in the
6370: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
6380: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
6390: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e s.xOpen] method.
63a0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
63b0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
63c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
63d0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 001 /* Ok for s
63e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
63f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6400: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
6410: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 E 0x00000
6420: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 002 /* Ok for s
6430: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
6440: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6450: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 TE_OPEN_CREATE
6460: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6470: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 004 /* Ok for s
6480: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
6490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
64a0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
64b0: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 CLOSE 0x00000
64c0: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 008 /* VFS only
64d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
64e0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 TE_OPEN_EXCLUSIV
64f0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 E 0x00000
6500: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 010 /* VFS only
6510: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6520: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 TE_OPEN_AUTOPROX
6530: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 Y 0x00000
6540: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 020 /* VFS only
6550: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6560: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 TE_OPEN_URI
6570: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6580: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 040 /* Ok for s
6590: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
65a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
65b0: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 TE_OPEN_MEMORY
65c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
65d0: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 080 /* Ok for s
65e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
65f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6600: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 TE_OPEN_MAIN_DB
6610: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6620: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 100 /* VFS only
6630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6640: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 TE_OPEN_TEMP_DB
6650: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6660: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 200 /* VFS only
6670: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6680: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e TE_OPEN_TRANSIEN
6690: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 T_DB 0x00000
66a0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 400 /* VFS only
66b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
66c0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 TE_OPEN_MAIN_JOU
66d0: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 RNAL 0x00000
66e0: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 800 /* VFS only
66f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6700: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 TE_OPEN_TEMP_JOU
6710: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 RNAL 0x00001
6720: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
6730: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6740: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e TE_OPEN_SUBJOURN
6750: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 AL 0x00002
6760: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
6770: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6780: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a TE_OPEN_MASTER_J
6790: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 OURNAL 0x00004
67a0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
67b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
67c0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 TE_OPEN_NOMUTEX
67d0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 0x00008
67e0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
67f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
6800: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6810: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 TE_OPEN_FULLMUTE
6820: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 X 0x00010
6830: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
6840: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
6850: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6860: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
6870: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 CHE 0x00020
6880: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
6890: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
68a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
68b0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
68c0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 ACHE 0x00040
68d0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
68e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
68f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6900: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 TE_OPEN_WAL
6910: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 0x00080
6920: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
6930: 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 */../* Reserved
6940: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 :
6950: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 0x00F0
6960: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 0000 */../*.** C
6970: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 API3REF: Device
6980: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a Characteristics.
6990: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 **.** The xDevic
69a0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 eCharacteristics
69b0: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b method of the [
69c0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
69d0: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 ds].** object re
69e0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 turns an integer
69f0: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 which is a vect
6a00: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 or of these.** b
6a10: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 it values expres
6a20: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 sing I/O charact
6a30: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 eristics of the
6a40: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 mass storage.**
6a50: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 device that hold
6a60: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 s the file that
6a70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
6a80: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 methods].** refe
6a90: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 rs to..**.** The
6aa0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6ab0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 OMIC property me
6ac0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 ans that all wri
6ad0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 tes of.** any si
6ae0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 ze are atomic.
6af0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
6b00: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 _ATOMICnnn value
6b10: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 s.** mean that w
6b20: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 rites of blocks
6b30: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 that are nnn byt
6b40: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a es in size and.*
6b50: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f * are aligned to
6b60: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 an address whic
6b70: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 h is an integer
6b80: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e multiple of.** n
6b90: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 nn are atomic.
6ba0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
6bb0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c _SAFE_APPEND val
6bc0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 ue means.** that
6bd0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 when data is ap
6be0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 pended to a file
6bf0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 , the data is ap
6c00: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 pended.** first
6c10: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 then the size of
6c20: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 the file is ext
6c30: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 ended, never the
6c40: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 other.** way ar
6c50: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 ound. The SQLIT
6c60: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
6c70: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e AL property mean
6c80: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d s that.** inform
6c90: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e ation is written
6ca0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 to disk in the
6cb0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 same order as ca
6cc0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 lls.** to xWrite
6cd0: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f (). The SQLITE_
6ce0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f IOCAP_POWERSAFE_
6cf0: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 OVERWRITE proper
6d00: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a ty means that.**
6d10: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f after reboot fo
6d20: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 llowing a crash
6d30: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 or power loss, t
6d40: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e he only bytes in
6d50: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 a.** file that
6d60: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 were written at
6d70: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
6d80: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 level might have
6d90: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 changed.** and
6da0: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 that adjacent by
6db0: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 tes, even bytes
6dc0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 within the same
6dd0: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 sector are.** gu
6de0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 aranteed to be u
6df0: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 nchanged. The S
6e00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 QLITE_IOCAP_UNDE
6e10: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 LETABLE_WHEN_OPE
6e20: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 N.** flag indica
6e30: 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 tes that a file
6e40: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 cannot be delete
6e50: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 d when open. Th
6e60: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 e.** SQLITE_IOCA
6e70: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 P_IMMUTABLE flag
6e80: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 indicates that
6e90: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a the file is on.*
6ea0: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 * read-only medi
6eb0: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 a and cannot be
6ec0: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 changed even by
6ed0: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a processes with.*
6ee0: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 * elevated privi
6ef0: 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 leges..**.** The
6f00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 SQLITE_IOCAP_BA
6f10: 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 TCH_ATOMIC prope
6f20: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74 rty means that t
6f30: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a he underlying.**
6f40: 20 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70 filesystem supp
6f50: 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 orts doing multi
6f60: 70 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74 ple write operat
6f70: 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 ions atomically
6f80: 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 when those.** wr
6f90: 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 ite operations a
6fa0: 72 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20 re bracketed by
6fb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 [SQLITE_FCNTL_BE
6fc0: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 GIN_ATOMIC_WRITE
6fd0: 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 ] and.** [SQLITE
6fe0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 _FCNTL_COMMIT_AT
6ff0: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a OMIC_WRITE]..*/.
7000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7010: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 OCAP_ATOMIC
7020: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
7030: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 000001.#define S
7040: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7050: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 IC512
7060: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 0x00000002.#d
7070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
7080: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 AP_ATOMIC1K
7090: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
70a0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 0004.#define SQL
70b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
70c0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2K
70d0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 0x00000008.#def
70e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
70f0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 _ATOMIC4K
7100: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
7110: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 10.#define SQLIT
7120: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b E_IOCAP_ATOMIC8K
7130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
7140: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e x00000020.#defin
7150: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
7160: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 TOMIC16K
7170: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0x00000040
7180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7190: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 IOCAP_ATOMIC32K
71a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
71b0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 0000080.#define
71c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
71d0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 MIC64K
71e0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 0x00000100.#
71f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
7200: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
7210: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
7220: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 00200.#define SQ
7230: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
7240: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 NTIAL
7250: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 0x00000400.#de
7260: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
7270: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 P_UNDELETABLE_WH
7280: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 EN_OPEN 0x00000
7290: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 800.#define SQLI
72a0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 TE_IOCAP_POWERSA
72b0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 FE_OVERWRITE
72c0: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 0x00001000.#defi
72d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
72e0: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 IMMUTABLE
72f0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 0x0000200
7300: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
7310: 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f _IOCAP_BATCH_ATO
7320: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78 MIC 0x
7330: 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 00004000../*.**
7340: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c CAPI3REF: File L
7350: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a ocking Levels.**
7360: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 .** SQLite uses
7370: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 one of these int
7380: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 eger values as t
7390: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 he second.** arg
73a0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 ument to calls i
73b0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 t makes to the x
73c0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f Lock() and xUnlo
73d0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 ck() methods.**
73e0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 of an [sqlite3_i
73f0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
7400: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t..*/.#define SQ
7410: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 LITE_LOCK_NONE
7420: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 0.#defin
7430: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 e SQLITE_LOCK_SH
7440: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 ARED 1.#d
7450: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
7460: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 K_RESERVED
7470: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
7480: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 _LOCK_PENDING
7490: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
74a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 LITE_LOCK_EXCLUS
74b0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a IVE 4../*.**
74c0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 CAPI3REF: Synch
74d0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 ronization Type
74e0: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e Flags.**.** When
74f0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 SQLite invokes
7500: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 the xSync() meth
7510: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c od of an.** [sql
7520: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
7530: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 object it uses
7540: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 a combination of
7550: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 .** these intege
7560: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 r values as the
7570: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e second argument.
7580: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
7590: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 SQLITE_SYNC_DATA
75a0: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 ONLY flag is use
75b0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 d, it means that
75c0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 the.** sync ope
75d0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 ration only need
75e0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 s to flush data
75f0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e to mass storage.
7600: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 Inode.** infor
7610: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 mation need not
7620: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 be flushed. If t
7630: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 he lower four bi
7640: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a ts of the flag.*
7650: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 * equal SQLITE_S
7660: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 YNC_NORMAL, that
7670: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f means to use no
7680: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d rmal fsync() sem
7690: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 antics..** If th
76a0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 e lower four bit
76b0: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 s equal SQLITE_S
76c0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d YNC_FULL, that m
76d0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d eans.** to use M
76e0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 ac OS X style fu
76f0: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f llsync instead o
7700: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a f fsync()..**.**
7710: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 Do not confuse
7720: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f the SQLITE_SYNC_
7730: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 NORMAL and SQLIT
7740: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 E_SYNC_FULL flag
7750: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 s.** with the [P
7760: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
7770: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 s]=NORMAL and [P
7780: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
7790: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 s]=FULL.** setti
77a0: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 ngs. The [synch
77b0: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 ronous pragma] d
77c0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 etermines when c
77d0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 alls to the.** x
77e0: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 Sync VFS method
77f0: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 occur and applie
7800: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f s uniformly acro
7810: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 ss all platforms
7820: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f ..** The SQLITE_
7830: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 SYNC_NORMAL and
7840: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
7850: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 flags determine
7860: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 how.** energeti
7870: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 c or rigorous or
7880: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 forceful the sy
7890: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 nc operations ar
78a0: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 e and.** only ma
78b0: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 ke a difference
78c0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 on Mac OSX for t
78d0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 he default SQLit
78e0: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 e code..** (Thir
78f0: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c d-party VFS impl
7900: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 ementations migh
7910: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 t also make the
7920: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 distinction.** b
7930: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 etween SQLITE_SY
7940: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 NC_NORMAL and SQ
7950: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 LITE_SYNC_FULL,
7960: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a but among the.**
7970: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
7980: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 ms natively supp
7990: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c orted by SQLite,
79a0: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a only Mac OSX.**
79b0: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 cares about the
79c0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f difference.).*/
79d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
79e0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 SYNC_NORMAL
79f0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 0x00002.#defi
7a00: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 ne SQLITE_SYNC_F
7a10: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 ULL 0x0
7a20: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 0003.#define SQL
7a30: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c ITE_SYNC_DATAONL
7a40: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a Y 0x00010..
7a50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
7a60: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 OS Interface Ope
7a70: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a n File Handle.**
7a80: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f .** An [sqlite3_
7a90: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 file] object rep
7aa0: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 resents an open
7ab0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 file in the .**
7ac0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f [sqlite3_vfs | O
7ad0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 S interface laye
7ae0: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 r]. Individual
7af0: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 OS interface.**
7b00: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
7b10: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 will.** want to
7b20: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 subclass this ob
7b30: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e ject by appendin
7b40: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 g additional fie
7b50: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 lds.** for their
7b60: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 own use. The p
7b70: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 Methods entry is
7b80: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
7b90: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f .** [sqlite3_io_
7ba0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
7bb0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 that defines met
7bc0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d hods for perform
7bd0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 ing.** I/O opera
7be0: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 tions on the ope
7bf0: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 n file..*/.typed
7c00: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
7c10: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 3_file sqlite3_f
7c20: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ile;.struct sqli
7c30: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e te3_file {. con
7c40: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 st struct sqlite
7c50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 3_io_methods *pM
7c60: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 ethods; /* Meth
7c70: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 ods for an open
7c80: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a file */.};../*.*
7c90: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 * CAPI3REF: OS I
7ca0: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 nterface File Vi
7cb0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 rtual Methods Ob
7cc0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 ject.**.** Every
7cd0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 file opened by
7ce0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
7cf0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 .xOpen] method p
7d00: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b opulates an.** [
7d10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
7d20: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 ject (or, more c
7d30: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c ommonly, a subcl
7d40: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 ass of the.** [s
7d50: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
7d60: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e ect) with a poin
7d70: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
7d80: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
7d90: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 t..** This objec
7da0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 t defines the me
7db0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 thods used to pe
7dc0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 rform various op
7dd0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 erations.** agai
7de0: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c nst the open fil
7df0: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 e represented by
7e00: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
7e10: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a le] object..**.*
7e20: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * If the [sqlite
7e30: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 3_vfs.xOpen] met
7e40: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c hod sets the sql
7e50: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
7e60: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 ds element .** t
7e70: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 o a non-NULL poi
7e80: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 nter, then the s
7e90: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
7ea0: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a s.xClose method.
7eb0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 ** may be invoke
7ec0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 d even if the [s
7ed0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
7ee0: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 ] reported that
7ef0: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a it failed. The.
7f00: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 ** only way to p
7f10: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f revent a call to
7f20: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e xClose followin
7f30: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 g a failed [sqli
7f40: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a te3_vfs.xOpen].*
7f50: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 * is for the [sq
7f60: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
7f70: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 to set the sqli
7f80: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
7f90: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 s element.** to
7fa0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 NULL..**.** The
7fb0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
7fc0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f o xSync may be o
7fd0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 ne of [SQLITE_SY
7fe0: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a NC_NORMAL] or.**
7ff0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 [SQLITE_SYNC_FU
8000: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 LL]. The first
8010: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f choice is the no
8020: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a rmal fsync()..**
8030: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 The second choi
8040: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 ce is a Mac OS X
8050: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e style fullsync.
8060: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 The [SQLITE_SY
8070: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 NC_DATAONLY].**
8080: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 flag may be ORed
8090: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 in to indicate
80a0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 that only the da
80b0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a ta of the file.*
80c0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e * and not its in
80d0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 ode needs to be
80e0: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 synced..**.** Th
80f0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
8100: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 to xLock() and
8110: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e xUnlock() are on
8120: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 e of.** <ul>.**
8130: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
8140: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e K_NONE],.** <li>
8150: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 [SQLITE_LOCK_SH
8160: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b ARED],.** <li> [
8170: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
8180: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b RVED],.** <li> [
8190: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 SQLITE_LOCK_PEND
81a0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e ING], or.** <li>
81b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 [SQLITE_LOCK_EX
81c0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 CLUSIVE]..** </u
81d0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e l>.** xLock() in
81e0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b creases the lock
81f0: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 . xUnlock() decr
8200: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a eases the lock..
8210: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 ** The xCheckRes
8220: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 ervedLock() meth
8230: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 od checks whethe
8240: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 r any database c
8250: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 onnection,.** ei
8260: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f ther in this pro
8270: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 cess or in some
8280: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 other process, i
8290: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 s holding a RESE
82a0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 RVED,.** PENDING
82b0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c , or EXCLUSIVE l
82c0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e ock on the file.
82d0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 It returns tru
82e0: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c e.** if such a l
82f0: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 ock exists and f
8300: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a alse otherwise..
8310: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 **.** The xFileC
8320: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 ontrol() method
8330: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 is a generic int
8340: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f erface that allo
8350: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 ws custom.** VFS
8360: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
8370: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e to directly con
8380: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c trol an open fil
8390: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b e using the.** [
83a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
83b0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 trol()] interfac
83c0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 e. The second "
83d0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 op" argument is
83e0: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 an.** integer op
83f0: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 code. The third
8400: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 argument is a g
8410: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 eneric pointer i
8420: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f ntended to.** po
8430: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 int to a structu
8440: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 re that may cont
8450: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 ain arguments or
8460: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 space in which
8470: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 to.** write retu
8480: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 rn values. Pote
8490: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 ntial uses for x
84a0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 FileControl() mi
84b0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 ght be.** functi
84c0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c ons to enable bl
84d0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 ocking locks wit
84e0: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 h timeouts, to c
84f0: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 hange the.** loc
8500: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 king strategy (f
8510: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 or example to us
8520: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 e dot-file locks
8530: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a ), to inquire.**
8540: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 about the statu
8550: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 s of a lock, or
8560: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c to break stale l
8570: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 ocks. The SQLit
8580: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 e.** core reserv
8590: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c es all opcodes l
85a0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 ess than 100 for
85b0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a its own use..**
85c0: 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c A [file control
85d0: 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 opcodes | list
85e0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 of opcodes] less
85f0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 than 100 is ava
8600: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 ilable..** Appli
8610: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 cations that def
8620: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 ine a custom xFi
8630: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
8640: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f should use opco
8650: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 des.** greater t
8660: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 han 100 to avoid
8670: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 conflicts. VFS
8680: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
8690: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 should.** retur
86a0: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 n [SQLITE_NOTFOU
86b0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e ND] for file con
86c0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 trol opcodes tha
86d0: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a t they do not.**
86e0: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a recognize..**.*
86f0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a * The xSectorSiz
8700: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 e() method retur
8710: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 ns the sector si
8720: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 ze of the.** dev
8730: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 ice that underli
8740: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 es the file. Th
8750: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 e sector size is
8760: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 the.** minimum
8770: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 write that can b
8780: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 e performed with
8790: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a out disturbing.*
87a0: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e * other bytes in
87b0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 the file. The
87c0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 xDeviceCharacter
87d0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 istics().** meth
87e0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 od returns a bit
87f0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 vector describi
8800: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 ng behaviors of
8810: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e the.** underlyin
8820: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 g device:.**.**
8830: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
8840: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8850: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 C].** <li> [SQLI
8860: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 TE_IOCAP_ATOMIC5
8870: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 12].** <li> [SQL
8880: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
8890: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 1K].** <li> [SQL
88a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
88b0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 2K].** <li> [SQL
88c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
88d0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 4K].** <li> [SQL
88e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
88f0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 8K].** <li> [SQL
8900: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
8910: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 16K].** <li> [SQ
8920: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8930: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C32K].** <li> [S
8940: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
8950: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC64K].** <li> [
8960: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 SQLITE_IOCAP_SAF
8970: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 E_APPEND].** <li
8980: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
8990: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c SEQUENTIAL].** <
89a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
89b0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 P_UNDELETABLE_WH
89c0: 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e EN_OPEN].** <li>
89d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 [SQLITE_IOCAP_P
89e0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
89f0: 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c TE].** <li> [SQL
8a00: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 ITE_IOCAP_IMMUTA
8a10: 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 BLE].** <li> [SQ
8a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 LITE_IOCAP_BATCH
8a30: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c _ATOMIC].** </ul
8a40: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 >.**.** The SQLI
8a50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 TE_IOCAP_ATOMIC
8a60: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
8a70: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f hat all writes o
8a80: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 f.** any size ar
8a90: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
8aa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
8ab0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 ICnnn values.**
8ac0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 mean that writes
8ad0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 of blocks that
8ae0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e are nnn bytes in
8af0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 size and.** are
8b00: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 aligned to an a
8b10: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 ddress which is
8b20: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 an integer multi
8b30: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 ple of.** nnn ar
8b40: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
8b50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
8b60: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 _APPEND value me
8b70: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e ans.** that when
8b80: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
8b90: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 d to a file, the
8ba0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
8bb0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 d.** first then
8bc0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
8bd0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 file is extended
8be0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 , never the othe
8bf0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e r.** way around.
8c00: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
8c10: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 AP_SEQUENTIAL pr
8c20: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
8c30: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e t.** information
8c40: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 is written to d
8c50: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 isk in the same
8c60: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a order as calls.*
8c70: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a * to xWrite()..*
8c80: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 *.** If xRead()
8c90: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 returns SQLITE_I
8ca0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 OERR_SHORT_READ
8cb0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c it must also fil
8cc0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 l.** in the unre
8cd0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 ad portions of t
8ce0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a he buffer with z
8cf0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 eros. A VFS tha
8d00: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 t.** fails to ze
8d10: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 ro-fill short re
8d20: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 ads might seem t
8d30: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 o work. However
8d40: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 ,.** failure to
8d50: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 zero-fill short
8d60: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 reads will event
8d70: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a ually lead to.**
8d80: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 database corrup
8d90: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 tion..*/.typedef
8da0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
8db0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 io_methods sqlit
8dc0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 e3_io_methods;.s
8dd0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f truct sqlite3_io
8de0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 _methods {. int
8df0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 iVersion;. int
8e00: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 (*xClose)(sqlit
8e10: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 e3_file*);. int
8e20: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 (*xRead)(sqlite
8e30: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 3_file*, void*,
8e40: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 int iAmt, sqlite
8e50: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 3_int64 iOfst);.
8e60: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 int (*xWrite)(
8e70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 sqlite3_file*, c
8e80: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 onst void*, int
8e90: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e iAmt, sqlite3_in
8ea0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e t64 iOfst);. in
8eb0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 t (*xTruncate)(s
8ec0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 qlite3_file*, sq
8ed0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 lite3_int64 size
8ee0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 );. int (*xSync
8ef0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
8f00: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 int flags);. i
8f10: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 nt (*xFileSize)(
8f20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 sqlite3_file*, s
8f30: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 qlite3_int64 *pS
8f40: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c ize);. int (*xL
8f50: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ock)(sqlite3_fil
8f60: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 e*, int);. int
8f70: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 (*xUnlock)(sqlit
8f80: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a e3_file*, int);.
8f90: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 int (*xCheckRe
8fa0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 servedLock)(sqli
8fb0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a te3_file*, int *
8fc0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 pResOut);. int
8fd0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 (*xFileControl)(
8fe0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
8ff0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 nt op, void *pAr
9000: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 g);. int (*xSec
9010: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 torSize)(sqlite3
9020: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 _file*);. int (
9030: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 *xDeviceCharacte
9040: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 ristics)(sqlite3
9050: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 _file*);. /* Me
9060: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
9070: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f valid for versio
9080: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 n 1 */. int (*x
9090: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f ShmMap)(sqlite3_
90a0: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 file*, int iPg,
90b0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 int pgsz, int, v
90c0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b oid volatile**);
90d0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 . int (*xShmLoc
90e0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a k)(sqlite3_file*
90f0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e , int offset, in
9100: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b t n, int flags);
9110: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 . void (*xShmBa
9120: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 rrier)(sqlite3_f
9130: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ile*);. int (*x
9140: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 ShmUnmap)(sqlite
9150: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 3_file*, int del
9160: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d eteFlag);. /* M
9170: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
9180: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 valid for versi
9190: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a on 2 */. int (*
91a0: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f xFetch)(sqlite3_
91b0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 file*, sqlite3_i
91c0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 nt64 iOfst, int
91d0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 iAmt, void **pp)
91e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 ;. int (*xUnfet
91f0: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ch)(sqlite3_file
9200: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
9210: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 iOfst, void *p)
9220: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 ;. /* Methods a
9230: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 bove are valid f
9240: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a or version 3 */.
9250: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 /* Additional
9260: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 methods may be a
9270: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
9280: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f eleases */.};../
9290: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
92a0: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e tandard File Con
92b0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 trol Opcodes.**
92c0: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 KEYWORDS: {file
92d0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d control opcodes}
92e0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f {file control o
92f0: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 pcode}.**.** The
9300: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 se integer const
9310: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 ants are opcodes
9320: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f for the xFileCo
9330: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 ntrol method.**
9340: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
9350: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
9360: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b ct and for the [
9370: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
9380: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 trol()].** inter
9390: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e face..**.** <ul>
93a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
93b0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
93c0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
93d0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
93e0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 E] opcode is use
93f0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e d for debugging.
9400: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 This.** opcode
9410: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c causes the xFil
9420: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
9430: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 to write the cur
9440: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a rent state of.**
9450: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f the lock (one o
9460: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e f [SQLITE_LOCK_N
9470: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f ONE], [SQLITE_LO
9480: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b CK_SHARED],.** [
9490: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
94a0: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c RVED], [SQLITE_L
94b0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 OCK_PENDING], or
94c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 [SQLITE_LOCK_EX
94d0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 CLUSIVE]).** int
94e0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 o an integer tha
94f0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d t the pArg argum
9500: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 ent points to. T
9510: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a his capability.*
9520: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 * is used during
9530: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 testing and is
9540: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 only available w
9550: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 hen the SQLITE_T
9560: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 EST.** compile-t
9570: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 ime option is us
9580: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ed..**.** <li>[[
9590: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a SQLITE_FCNTL_SIZ
95a0: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 E_HINT]].** The
95b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 [SQLITE_FCNTL_SI
95c0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 ZE_HINT] opcode
95d0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 is used by SQLit
95e0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 e to give the VF
95f0: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e S.** layer a hin
9600: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 t of how large t
9610: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
9620: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 will grow to be
9630: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 during the.** c
9640: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 urrent transacti
9650: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 on. This hint i
9660: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 s not guaranteed
9670: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 to be accurate
9680: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 but it.** is oft
9690: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 en close. The u
96a0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 nderlying VFS mi
96b0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 ght choose to pr
96c0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 eallocate databa
96d0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 se.** file space
96e0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 based on this h
96f0: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 int in order to
9700: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 help writes to t
9710: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 he database.** f
9720: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a ile run faster..
9730: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
9740: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 4c 49 TE_FCNTL_SIZE_LI
9750: 4d 49 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 MIT]].** The [SQ
9760: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f LITE_FCNTL_SIZE_
9770: 4c 49 4d 49 54 5d 20 6f 70 63 6f 64 65 20 69 73 LIMIT] opcode is
9780: 20 75 73 65 64 20 62 79 20 69 6e 2d 6d 65 6d 6f used by in-memo
9790: 72 79 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 69 ry VFS that.** i
97a0: 6d 70 6c 65 6d 65 6e 74 73 20 5b 73 71 6c 69 74 mplements [sqlit
97b0: 65 33 5f 64 65 73 65 72 69 61 6c 69 7a 65 28 29 e3_deserialize()
97c0: 5d 20 74 6f 20 73 65 74 20 61 6e 20 75 70 70 65 ] to set an uppe
97d0: 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 r bound on the s
97e0: 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e ize.** of the in
97f0: 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
9800: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 . The argument
9810: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
9820: 61 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 a [sqlite3_int64
9830: 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 ]..** If the int
9840: 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20 eger pointed to
9850: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
9860: 6e 20 69 74 20 69 73 20 66 69 6c 6c 65 64 20 69 n it is filled i
9870: 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 63 75 n with the.** cu
9880: 72 72 65 6e 74 20 6c 69 6d 69 74 2e 20 20 4f 74 rrent limit. Ot
9890: 68 65 72 77 69 73 65 20 74 68 65 20 6c 69 6d 69 herwise the limi
98a0: 74 20 69 73 20 73 65 74 20 74 6f 20 74 68 65 20 t is set to the
98b0: 6c 61 72 67 65 72 20 6f 66 20 74 68 65 20 76 61 larger of the va
98c0: 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e lue.** of the in
98d0: 74 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f teger pointed to
98e0: 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 and the current
98f0: 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 2e 20 database size.
9900: 20 54 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 The integer.**
9910: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 73 65 pointed to is se
9920: 74 20 74 6f 20 74 68 65 20 6e 65 77 20 6c 69 6d t to the new lim
9930: 69 74 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b it..**.** <li>[[
9940: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 SQLITE_FCNTL_CHU
9950: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 NK_SIZE]].** The
9960: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 [SQLITE_FCNTL_C
9970: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 HUNK_SIZE] opcod
9980: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 e is used to req
9990: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 uest that the VF
99a0: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 S.** extends and
99b0: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 truncates the d
99c0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 atabase file in
99d0: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 chunks of a size
99e0: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 specified.** by
99f0: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 the user. The f
9a00: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 ourth argument t
9a10: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f o [sqlite3_file_
9a20: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c control()] shoul
9a30: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 d .** point to a
9a40: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 n integer (type
9a50: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 int) containing
9a60: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 the new chunk-si
9a70: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 ze to use.** for
9a80: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 the nominated d
9a90: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 atabase. Allocat
9aa0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c ing database fil
9ab0: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 e space in large
9ac0: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 .** chunks (say
9ad0: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 1MB at a time),
9ae0: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d may reduce file-
9af0: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 system fragmenta
9b00: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 tion and.** impr
9b10: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 ove performance
9b20: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e on some systems.
9b30: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
9b40: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 ITE_FCNTL_FILE_P
9b50: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 OINTER]].** The
9b60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 [SQLITE_FCNTL_FI
9b70: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f LE_POINTER] opco
9b80: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 de is used to ob
9b90: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a tain a pointer.*
9ba0: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 * to the [sqlite
9bb0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 3_file] object a
9bc0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 ssociated with a
9bd0: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 particular data
9be0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
9bf0: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 on. See also [S
9c00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 QLITE_FCNTL_JOUR
9c10: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a NAL_POINTER]..**
9c20: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
9c30: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 _FCNTL_JOURNAL_P
9c40: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 OINTER]].** The
9c50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f [SQLITE_FCNTL_JO
9c60: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f URNAL_POINTER] o
9c70: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
9c80: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 obtain a pointe
9c90: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c r.** to the [sql
9ca0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
9cb0: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 t associated wit
9cc0: 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 h the journal fi
9cd0: 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 le (either.** th
9ce0: 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 e [rollback jour
9cf0: 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 nal] or the [wri
9d00: 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 te-ahead log]) f
9d10: 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 or a particular
9d20: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
9d30: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 ection. See als
9d40: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f o [SQLITE_FCNTL_
9d50: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a FILE_POINTER]..*
9d60: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
9d70: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 E_FCNTL_SYNC_OMI
9d80: 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e TTED]].** No lon
9d90: 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a ger in use..**.*
9da0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
9db0: 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 CNTL_SYNC]].** T
9dc0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
9dd0: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 _SYNC] opcode is
9de0: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 generated inter
9df0: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 nally by SQLite
9e00: 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 and.** sent to t
9e10: 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 he VFS immediate
9e20: 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 ly before the xS
9e30: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e ync method is in
9e40: 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 voked on a.** da
9e50: 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 tabase file desc
9e60: 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 riptor. Or, if t
9e70: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 he xSync method
9e80: 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a is not invoked .
9e90: 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75 ** because the u
9ea0: 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 ser has configur
9eb0: 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a ed SQLite with .
9ec0: 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 ** [PRAGMA synch
9ed0: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 ronous | PRAGMA
9ee0: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d synchronous=OFF]
9ef0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 it is invoked i
9f00: 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 n place .** of t
9f10: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e he xSync method.
9f20: 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 In most cases,
9f30: 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 the pointer argu
9f40: 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 ment passed with
9f50: 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f .** this file-co
9f60: 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 ntrol is NULL. H
9f70: 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 owever, if the d
9f80: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 atabase file is
9f90: 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 being synced.**
9fa0: 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c as part of a mul
9fb0: 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d ti-database comm
9fc0: 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 it, the argument
9fd0: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c points to a nul
9fe0: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 -terminated.** s
9ff0: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 tring containing
a000: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
a010: 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c s master-journal
a020: 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 file name. VFSe
a030: 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f s that .** do no
a040: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e t need this sign
a050: 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 al should silent
a060: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f ly ignore this o
a070: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 pcode. Applicati
a080: 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e ons .** should n
a090: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 ot call [sqlite3
a0a0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
a0b0: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 with this opcod
a0c0: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 e as doing so ma
a0d0: 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 y .** disrupt th
a0e0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 e operation of t
a0f0: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 he specialized V
a100: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 FSes that do req
a110: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a uire it. .**.**
a120: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
a130: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 NTL_COMMIT_PHASE
a140: 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 TWO]].** The [SQ
a150: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 LITE_FCNTL_COMMI
a160: 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f T_PHASETWO] opco
a170: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 de is generated
a180: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 internally by SQ
a190: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 Lite.** and sent
a1a0: 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 to the VFS afte
a1b0: 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 r a transaction
a1c0: 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 has been committ
a1d0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a ed immediately.*
a1e0: 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 * but before the
a1f0: 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c database is unl
a200: 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 ocked. VFSes tha
a210: 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 t do not need th
a220: 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f is signal.** sho
a230: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e uld silently ign
a240: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e ore this opcode.
a250: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 Applications sh
a260: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a ould not call.**
a270: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
a280: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 ontrol()] with t
a290: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f his opcode as do
a2a0: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 ing so may disru
a2b0: 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 pt the .** opera
a2c0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 tion of the spec
a2d0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 ialized VFSes th
a2e0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 at do require it
a2f0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b . .**.** <li>[[
a300: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
a310: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 32_AV_RETRY]].**
a320: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^The [SQLITE_FC
a330: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 NTL_WIN32_AV_RET
a340: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 RY] opcode is us
a350: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 ed to configure
a360: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 automatic.** ret
a370: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e ry counts and in
a380: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 tervals for cert
a390: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 ain disk I/O ope
a3a0: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a rations for the.
a3b0: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d ** windows [VFS]
a3c0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f in order to pro
a3d0: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 vide robustness
a3e0: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 in the presence
a3f0: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 of.** anti-virus
a400: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 programs. By d
a410: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 efault, the wind
a420: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 ows VFS will ret
a430: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a ry file read,.**
a440: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 file write, and
a450: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 file delete ope
a460: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 rations up to 10
a470: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 times, with a d
a480: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 elay.** of 25 mi
a490: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 lliseconds befor
a4a0: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 e the first retr
a4b0: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 y and with the d
a4c0: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a elay increasing.
a4d0: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f ** by an additio
a4e0: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f nal 25 milliseco
a4f0: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 nds with each su
a500: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 bsequent retry.
a510: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 This.** opcode
a520: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f allows these two
a530: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 values (10 retr
a540: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 ies and 25 milli
a550: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 seconds of delay
a560: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 ).** to be adjus
a570: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 ted. The values
a580: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 are changed for
a590: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f all database co
a5a0: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 nnections.** wit
a5b0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f hin the same pro
a5c0: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d cess. The argum
a5d0: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
a5e0: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 to an array of
a5f0: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 two.** integers
a600: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20 where the first
a610: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 6e integer is the n
a620: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 ew retry count a
a630: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a nd the second.**
a640: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 integer is the
a650: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 delay. If eithe
a660: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 r integer is neg
a670: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 ative, then the
a680: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f setting.** is no
a690: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e t changed but in
a6a0: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 stead the prior
a6b0: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 value of that se
a6c0: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e tting is written
a6d0: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 .** into the arr
a6e0: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 ay entry, allowi
a6f0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 ng the current r
a700: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f etry settings to
a710: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 be.** interroga
a720: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d ted. The zDbNam
a730: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 e parameter is i
a740: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c gnored..**.** <l
a750: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
a760: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a _PERSIST_WAL]].*
a770: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
a780: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c CNTL_PERSIST_WAL
a790: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
a7a0: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 to set or query
a7b0: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 the.** persiste
a7c0: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 nt [WAL | Write
a7d0: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 Ahead Log] setti
a7e0: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c ng. By default,
a7f0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a the auxiliary.*
a800: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f * write ahead lo
a810: 67 20 28 5b 57 41 4c 20 66 69 6c 65 5d 29 20 61 g ([WAL file]) a
a820: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 nd shared memory
a830: 0a 2a 2a 20 66 69 6c 65 73 20 75 73 65 64 20 66 .** files used f
a840: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 or transaction c
a850: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 ontrol.** are au
a860: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 tomatically dele
a870: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 ted when the lat
a880: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 est connection t
a890: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a o the database.*
a8a0: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 * closes. Setti
a8b0: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 ng persistent WA
a8c0: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 L mode causes th
a8d0: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 ose files to per
a8e0: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c sist after.** cl
a8f0: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 ose. Persisting
a900: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 the files is us
a910: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 eful when other
a920: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 processes that d
a930: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 o not.** have wr
a940: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f ite permission o
a950: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 n the directory
a960: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 containing the d
a970: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e atabase file wan
a980: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 t.** to read the
a990: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
a9a0: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 as the WAL and s
a9b0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c hared memory fil
a9c0: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a es must exist.**
a9d0: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 in order for th
a9e0: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 e database to be
a9f0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 readable. The
aa00: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
aa10: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
aa20: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
aa30: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 for this opcode
aa40: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e should be a poin
aa50: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
aa60: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 r..** That integ
aa70: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 er is 0 to disab
aa80: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 le persistent WA
aa90: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 L mode or 1 to e
aaa0: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 nable persistent
aab0: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 .** WAL mode. I
aac0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 f the integer is
aad0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 -1, then it is
aae0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 overwritten with
aaf0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
ab00: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 WAL persistence
ab10: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c setting..**.** <
ab20: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
ab30: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 L_POWERSAFE_OVER
ab40: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 WRITE]].** ^The
ab50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f [SQLITE_FCNTL_PO
ab60: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 WERSAFE_OVERWRIT
ab70: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 E] opcode is use
ab80: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 d to set or quer
ab90: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 y the.** persist
aba0: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f ent "powersafe-o
abb0: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 verwrite" or "PS
abc0: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 OW" setting. Th
abd0: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a e PSOW setting.*
abe0: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 * determines the
abf0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 [SQLITE_IOCAP_P
ac00: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
ac10: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a TE] bit of the.*
ac20: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 * xDeviceCharact
ac30: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 eristics methods
ac40: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 . The fourth par
ac50: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 ameter to.** [sq
ac60: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
ac70: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f ol()] for this o
ac80: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 pcode should be
ac90: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
aca0: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 integer..** That
acb0: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f integer is 0 to
acc0: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 disable zero-da
acd0: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 mage mode or 1 t
ace0: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 o enable zero-da
acf0: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 mage.** mode. I
ad00: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 f the integer is
ad10: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 -1, then it is
ad20: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 overwritten with
ad30: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
ad40: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 zero-damage mode
ad50: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 setting..**.**
ad60: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
ad70: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a TL_OVERWRITE]].*
ad80: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
ad90: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 CNTL_OVERWRITE]
ada0: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 opcode is invoke
adb0: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 d by SQLite afte
adc0: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 r opening.** a w
add0: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e rite transaction
ade0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
adf0: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 t, unless it is
ae00: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 rolled back for
ae10: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 some.** reason,
ae20: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 the entire datab
ae30: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 ase file will be
ae40: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 overwritten by
ae50: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 the current .**
ae60: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 transaction. Thi
ae70: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 s is used by VAC
ae80: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a UUM operations..
ae90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
aea0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 TE_FCNTL_VFSNAME
aeb0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 ]].** ^The [SQLI
aec0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 TE_FCNTL_VFSNAME
aed0: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 ] opcode can be
aee0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 used to obtain t
aef0: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 he names of.** a
af00: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 ll [VFSes] in th
af10: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 e VFS stack. Th
af20: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 e names are of a
af30: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 ll VFS shims and
af40: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f the.** final bo
af50: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 ttom-level VFS a
af60: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 re written into
af70: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
af80: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 from .** [sqlite
af90: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 3_malloc()] and
afa0: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 the result is st
afb0: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 ored in the char
afc0: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 * variable.** th
afd0: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 at the fourth pa
afe0: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 rameter of [sqli
aff0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
b000: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a ()] points to..*
b010: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 * The caller is
b020: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 responsible for
b030: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f freeing the memo
b040: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 ry when done. A
b050: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 s with.** all fi
b060: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f le-control actio
b070: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 ns, there is no
b080: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 guarantee that t
b090: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c his will actuall
b0a0: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 y.** do anything
b0b0: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c . Callers shoul
b0c0: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 d initialize the
b0d0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 char* variable
b0e0: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 to a NULL.** poi
b0f0: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 nter in case thi
b100: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 s file-control i
b110: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 s not implemente
b120: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f d. This file-co
b130: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 ntrol.** is inte
b140: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 nded for diagnos
b150: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a tic use only..**
b160: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
b170: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 _FCNTL_VFS_POINT
b180: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ER]].** ^The [SQ
b190: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 LITE_FCNTL_VFS_P
b1a0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 OINTER] opcode f
b1b0: 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74 inds a pointer t
b1c0: 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a o the top-level.
b1d0: 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65 ** [VFSes] curre
b1e0: 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 ntly in use. ^(
b1f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69 The argument X i
b200: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c n.** sqlite3_fil
b210: 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c e_control(db,SQL
b220: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f ITE_FCNTL_VFS_PO
b230: 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65 INTER,X) must be
b240: 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71 .** of type "[sq
b250: 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 lite3_vfs] **".
b260: 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69 This opcodes wi
b270: 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 ll set *X.** to
b280: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
b290: 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 top-level VFS.)
b2a0: 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 ^.** ^When there
b2b0: 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 are multiple VF
b2c0: 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73 S shims in the s
b2d0: 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 tack, this opcod
b2e0: 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 e finds the.** u
b2f0: 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f pper-most shim o
b300: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b nly..**.** <li>[
b310: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
b320: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 AGMA]].** ^Whene
b330: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 ver a [PRAGMA] s
b340: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 tatement is pars
b350: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 ed, an [SQLITE_F
b360: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a CNTL_PRAGMA] .**
b370: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 file control is
b380: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 sent to the ope
b390: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d n [sqlite3_file]
b3a0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f object correspo
b3b0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 nding.** to the
b3c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f database file to
b3d0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d which the pragm
b3e0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 a statement refe
b3f0: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e rs. ^The argumen
b400: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c t.** to the [SQL
b410: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
b420: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 ] file control i
b430: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a s an array of.**
b440: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
b450: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e ings (char**) in
b460: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e which the secon
b470: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 d element of the
b480: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 array.** is the
b490: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 name of the pra
b4a0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 gma and the thir
b4b0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 d element is the
b4c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
b4d0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 .** pragma or NU
b4e0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 LL if the pragma
b4f0: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 has no argument
b500: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 . ^The handler
b510: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 for an.** [SQLIT
b520: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
b530: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e file control can
b540: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 optionally make
b550: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 the first eleme
b560: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 nt.** of the cha
b570: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 r** argument poi
b580: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f nt to a string o
b590: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
b5a0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d lite3_mprintf()]
b5b0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 .** or the equiv
b5c0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 alent and that s
b5d0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d tring will becom
b5e0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 e the result of
b5f0: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a the pragma or.**
b600: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
b610: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 ge if the pragma
b620: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a fails. ^If the.
b630: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c ** [SQLITE_FCNTL
b640: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
b650: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 ntrol returns [S
b660: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c QLITE_NOTFOUND],
b670: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a then normal .**
b680: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 [PRAGMA] proces
b690: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 sing continues.
b6a0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 ^If the [SQLITE
b6b0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a _FCNTL_PRAGMA].*
b6c0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 * file control r
b6d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
b6e0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 K], then the par
b6f0: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 ser assumes that
b700: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 the.** VFS has
b710: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 handled the PRAG
b720: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 MA itself and th
b730: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 e parser generat
b740: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 es a no-op.** pr
b750: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
b760: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e if result strin
b770: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 g is NULL, or th
b780: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 at returns a cop
b790: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 y.** of the resu
b7a0: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65 lt string if the
b7b0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e string is non-N
b7c0: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ULL..** ^If the
b7d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
b7e0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 AGMA] file contr
b7f0: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e ol returns.** an
b800: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 y result code ot
b810: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
b820: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f _OK] or [SQLITE_
b830: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 NOTFOUND], that
b840: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 means.** that th
b850: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 e VFS encountere
b860: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 d an error while
b870: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 handling the [P
b880: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a RAGMA] and the.*
b890: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 * compilation of
b8a0: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c the PRAGMA fail
b8b0: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e s with an error.
b8c0: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ^The [SQLITE_F
b8d0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 CNTL_PRAGMA].**
b8e0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 file control occ
b8f0: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e urs at the begin
b900: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 ning of pragma s
b910: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 tatement analysi
b920: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 s and so.** it i
b930: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 s able to overri
b940: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 de built-in [PRA
b950: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e GMA] statements.
b960: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
b970: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 ITE_FCNTL_BUSYHA
b980: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 NDLER]].** ^The
b990: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 [SQLITE_FCNTL_BU
b9a0: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 SYHANDLER].** fi
b9b0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 le-control may b
b9c0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c e invoked by SQL
b9d0: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 ite on the datab
b9e0: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a ase file handle.
b9f0: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 ** shortly after
ba00: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e it is opened in
ba10: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 order to provid
ba20: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 e a custom VFS w
ba30: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f ith access.** to
ba40: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 the connections
ba50: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 busy-handler ca
ba60: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 llback. The argu
ba70: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 ment is of type
ba80: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 (void **).** - a
ba90: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 n array of two (
baa0: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 void *) values.
bab0: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 The first (void
bac0: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e *) actually poin
bad0: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 ts.** to a funct
bae0: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 ion of type (int
baf0: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 (*)(void *)). I
bb00: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b n order to invok
bb10: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e e the connection
bb20: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 s.** busy-handle
bb30: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e r, this function
bb40: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b should be invok
bb50: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f ed with the seco
bb60: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a nd (void *) in.*
bb70: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74 * the array as t
bb80: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 he only argument
bb90: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 . If it returns
bba0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 non-zero, then t
bbb0: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 he operation.**
bbc0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 should be retrie
bbd0: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 d. If it returns
bbe0: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f zero, the custo
bbf0: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 m VFS should aba
bc00: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 ndon the.** curr
bc10: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a ent operation..*
bc20: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
bc30: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 E_FCNTL_TEMPFILE
bc40: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 NAME]].** ^Appli
bc50: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b cation can invok
bc60: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 e the [SQLITE_FC
bc70: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 NTL_TEMPFILENAME
bc80: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a ] file-control.*
bc90: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 * to have SQLite
bca0: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 generate a.** t
bcb0: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d emporary filenam
bcc0: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 e using the same
bcd0: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 algorithm that
bce0: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 is followed to g
bcf0: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f enerate.** tempo
bd00: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 rary filenames f
bd10: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 or TEMP tables a
bd20: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 nd other interna
bd30: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 l uses. The.**
bd40: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
bd50: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 be a char** whic
bd60: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 h will be filled
bd70: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 with the filena
bd80: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e me.** written in
bd90: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
bda0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
bdb0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 _malloc()]. The
bdc0: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a caller should.*
bdd0: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 * invoke [sqlite
bde0: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 3_free()] on the
bdf0: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 result to avoid
be00: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a a memory leak..
be10: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
be20: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 TE_FCNTL_MMAP_SI
be30: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ZE]].** The [SQL
be40: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 ITE_FCNTL_MMAP_S
be50: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f IZE] file contro
be60: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 l is used to que
be70: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a ry or set the.**
be80: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
be90: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69 of bytes that wi
bea0: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d ll be used for m
beb0: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f emory-mapped I/O
bec0: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e ..** The argumen
bed0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
bee0: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 o a value of typ
bef0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 e sqlite3_int64
bf00: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 that.** is an ad
bf10: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e visory maximum n
bf20: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
bf30: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 n the file to me
bf40: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a mory map. The.*
bf50: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 * pointer is ove
bf60: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 rwritten with th
bf70: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 e old value. Th
bf80: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 e limit is not c
bf90: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 hanged if.** the
bfa0: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c value originall
bfb0: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 y pointed to is
bfc0: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f negative, and so
bfd0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d the current lim
bfe0: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 it .** can be qu
bff0: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 eried by passing
c000: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f in a pointer to
c010: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 a negative numb
c020: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c er. This.** fil
c030: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 e-control is use
c040: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 d internally to
c050: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d implement [PRAGM
c060: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a A mmap_size]..**
c070: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
c080: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a _FCNTL_TRACE]].*
c090: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
c0a0: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 NTL_TRACE] file
c0b0: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 control provides
c0c0: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d advisory inform
c0d0: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 ation.** to the
c0e0: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 VFS about what t
c0f0: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 he higher layers
c100: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 of the SQLite s
c110: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a tack are doing..
c120: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e ** This file con
c130: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 trol is used by
c140: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 some VFS activit
c150: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 y tracing [shims
c160: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 ]..** The argume
c170: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 nt is a zero-ter
c180: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 minated string.
c190: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 Higher layers i
c1a0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 n the.** SQLite
c1b0: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 stack may genera
c1c0: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 te instances of
c1d0: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f this file contro
c1e0: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c l if.** the [SQL
c1f0: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 ITE_USE_FCNTL_TR
c200: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d ACE] compile-tim
c210: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 e option is enab
c220: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b led..**.** <li>[
c230: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 [SQLITE_FCNTL_HA
c240: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 S_MOVED]].** The
c250: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 [SQLITE_FCNTL_H
c260: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 AS_MOVED] file c
c270: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 ontrol interpret
c280: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 s its argument a
c290: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 s a.** pointer t
c2a0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 o an integer and
c2b0: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f it writes a boo
c2c0: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 lean into that i
c2d0: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 nteger depending
c2e0: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f .** on whether o
c2f0: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 r not the file h
c300: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c as been renamed,
c310: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 moved, or delet
c320: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 ed since it.** w
c330: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e as first opened.
c340: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
c350: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
c360: 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 GET_HANDLE]].**
c370: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
c380: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 L_WIN32_GET_HAND
c390: 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 LE] opcode can b
c3a0: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e e used to obtain
c3b0: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 the.** underlyi
c3c0: 6e 67 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 ng native file h
c3d0: 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64 andle associated
c3e0: 20 77 69 74 68 20 61 20 66 69 6c 65 20 68 61 6e with a file han
c3f0: 64 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65 0a dle. This file.
c400: 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 ** control inter
c410: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 prets its argume
c420: 6e 74 20 61 73 20 61 20 70 6f 69 6e 74 65 72 20 nt as a pointer
c430: 74 6f 20 61 20 6e 61 74 69 76 65 20 66 69 6c 65 to a native file
c440: 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 handle and.** w
c450: 72 69 74 65 73 20 74 68 65 20 72 65 73 75 6c 74 rites the result
c460: 69 6e 67 20 76 61 6c 75 65 20 74 68 65 72 65 2e ing value there.
c470: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
c480: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
c490: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 SET_HANDLE]].**
c4a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
c4b0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 L_WIN32_SET_HAND
c4c0: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 LE] opcode is us
c4d0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 ed for debugging
c4e0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 . This.** opcod
c4f0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 e causes the xFi
c500: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
c510: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c to swap the fil
c520: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 e handle with th
c530: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 e one.** pointed
c540: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 to by the pArg
c550: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 argument. This
c560: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 capability is us
c570: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
c580: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 g.** and only ne
c590: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 eds to be suppor
c5a0: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f ted when SQLITE_
c5b0: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e TEST is defined.
c5c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
c5d0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c ITE_FCNTL_WAL_BL
c5e0: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 OCK]].** The [SQ
c5f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 LITE_FCNTL_WAL_B
c600: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 LOCK] is a signa
c610: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 l to the VFS lay
c620: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 er that it might
c630: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 .** be advantage
c640: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 ous to block on
c650: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 the next WAL loc
c660: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 k if the lock is
c670: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 not immediately
c680: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 .** available.
c690: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 The WAL subsyste
c6a0: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69 m issues this si
c6b0: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 gnal during rare
c6c0: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 .** circumstance
c6d0: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 s in order to fi
c6e0: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 x a problem with
c6f0: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 priority invers
c700: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 ion..** Applicat
c710: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e ions should <em>
c720: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 not</em> use thi
c730: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a s file-control..
c740: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
c750: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d TE_FCNTL_ZIPVFS]
c760: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
c770: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f _FCNTL_ZIPVFS] o
c780: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 pcode is impleme
c790: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f nted by zipvfs o
c7a0: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a nly. All other.*
c7b0: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 * VFS should ret
c7c0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f urn SQLITE_NOTFO
c7d0: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63 UND for this opc
c7e0: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ode..**.** <li>[
c7f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 [SQLITE_FCNTL_RB
c800: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 U]].** The [SQLI
c810: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 TE_FCNTL_RBU] op
c820: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e code is implemen
c830: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69 ted by the speci
c840: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a al VFS used by.*
c850: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73 * the RBU extens
c860: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f ion only. All o
c870: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20 ther VFS should
c880: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f return SQLITE_NO
c890: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 TFOUND for.** th
c8a0: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a is opcode. .**.
c8b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
c8c0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d FCNTL_BEGIN_ATOM
c8d0: 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49 66 IC_WRITE]].** If
c8e0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e the [SQLITE_FCN
c8f0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f TL_BEGIN_ATOMIC_
c900: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 72 65 WRITE] opcode re
c910: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2c turns SQLITE_OK,
c920: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 66 69 6c then.** the fil
c930: 65 20 64 65 73 63 72 69 70 74 6f 72 20 69 73 20 e descriptor is
c940: 70 6c 61 63 65 64 20 69 6e 20 22 62 61 74 63 68 placed in "batch
c950: 20 77 72 69 74 65 20 6d 6f 64 65 22 2c 20 77 68 write mode", wh
c960: 69 63 68 0a 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c ich.** means all
c970: 20 73 75 62 73 65 71 75 65 6e 74 20 77 72 69 74 subsequent writ
c980: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 69 6c e operations wil
c990: 6c 20 62 65 20 64 65 66 65 72 72 65 64 20 61 6e l be deferred an
c9a0: 64 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63 d done.** atomic
c9b0: 61 6c 6c 79 20 61 74 20 74 68 65 20 6e 65 78 74 ally at the next
c9c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 [SQLITE_FCNTL_C
c9d0: 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 OMMIT_ATOMIC_WRI
c9e0: 54 45 5d 2e 20 20 53 79 73 74 65 6d 73 0a 2a 2a TE]. Systems.**
c9f0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 73 75 70 that do not sup
ca00: 70 6f 72 74 20 62 61 74 63 68 20 61 74 6f 6d 69 port batch atomi
ca10: 63 20 77 72 69 74 65 73 20 77 69 6c 6c 20 72 65 c writes will re
ca20: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 turn SQLITE_NOTF
ca30: 4f 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 OUND..** ^Follow
ca40: 69 6e 67 20 61 20 73 75 63 63 65 73 73 66 75 6c ing a successful
ca50: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 SQLITE_FCNTL_BE
ca60: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 GIN_ATOMIC_WRITE
ca70: 20 61 6e 64 20 70 72 69 6f 72 20 74 6f 0a 2a 2a and prior to.**
ca80: 20 74 68 65 20 63 6c 6f 73 69 6e 67 20 5b 53 51 the closing [SQ
ca90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 LITE_FCNTL_COMMI
caa0: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 T_ATOMIC_WRITE]
cab0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 or.** [SQLITE_FC
cac0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f NTL_ROLLBACK_ATO
cad0: 4d 49 43 5f 57 52 49 54 45 5d 2c 20 53 51 4c 69 MIC_WRITE], SQLi
cae0: 74 65 20 77 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 te will make.**
caf0: 6e 6f 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 no VFS interface
cb00: 20 63 61 6c 6c 73 20 6f 6e 20 74 68 65 20 73 61 calls on the sa
cb10: 6d 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 me [sqlite3_file
cb20: 5d 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f ] file descripto
cb30: 72 0a 2a 2a 20 65 78 63 65 70 74 20 66 6f 72 20 r.** except for
cb40: 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 78 57 72 calls to the xWr
cb50: 69 74 65 20 6d 65 74 68 6f 64 20 61 6e 64 20 74 ite method and t
cb60: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 he xFileControl
cb70: 6d 65 74 68 6f 64 0a 2a 2a 20 77 69 74 68 20 5b method.** with [
cb80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a SQLITE_FCNTL_SIZ
cb90: 45 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c E_HINT]..**.** <
cba0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
cbb0: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f L_COMMIT_ATOMIC_
cbc0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b WRITE]].** The [
cbd0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d SQLITE_FCNTL_COM
cbe0: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 MIT_ATOMIC_WRITE
cbf0: 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 ] opcode causes
cc00: 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 all write.** ope
cc10: 72 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 rations since th
cc20: 65 20 70 72 65 76 69 6f 75 73 20 73 75 63 63 65 e previous succe
cc30: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a ssful call to .*
cc40: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f * [SQLITE_FCNTL_
cc50: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 BEGIN_ATOMIC_WRI
cc60: 54 45 5d 20 74 6f 20 62 65 20 70 65 72 66 6f 72 TE] to be perfor
cc70: 6d 65 64 20 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a med atomically..
cc80: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e ** This file con
cc90: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 trol returns [SQ
cca0: 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6e 64 20 LITE_OK] if and
ccb0: 6f 6e 6c 79 20 69 66 20 74 68 65 20 77 72 69 74 only if the writ
ccc0: 65 73 20 77 65 72 65 0a 2a 2a 20 61 6c 6c 20 70 es were.** all p
ccd0: 65 72 66 6f 72 6d 65 64 20 73 75 63 63 65 73 73 erformed success
cce0: 66 75 6c 6c 79 20 61 6e 64 20 68 61 76 65 20 62 fully and have b
ccf0: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 74 6f een committed to
cd00: 20 70 65 72 73 69 73 74 65 6e 74 20 73 74 6f 72 persistent stor
cd10: 61 67 65 2e 0a 2a 2a 20 5e 52 65 67 61 72 64 6c age..** ^Regardl
cd20: 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
cd30: 72 20 6e 6f 74 20 69 74 20 69 73 20 73 75 63 63 r not it is succ
cd40: 65 73 73 66 75 6c 2c 20 74 68 69 73 20 66 69 6c essful, this fil
cd50: 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 0a e control takes.
cd60: 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 ** the file desc
cd70: 72 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 riptor out of ba
cd80: 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 20 73 tch write mode s
cd90: 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65 o that all subse
cda0: 71 75 65 6e 74 0a 2a 2a 20 77 72 69 74 65 20 6f quent.** write o
cdb0: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e perations are in
cdc0: 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 dependent..** ^S
cdd0: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 QLite will never
cde0: 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 invoke SQLITE_F
cdf0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d CNTL_COMMIT_ATOM
ce00: 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 IC_WRITE without
ce10: 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 .** a prior succ
ce20: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
ce30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 SQLITE_FCNTL_BEG
ce40: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d IN_ATOMIC_WRITE]
ce50: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
ce60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 LITE_FCNTL_ROLLB
ce70: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 ACK_ATOMIC_WRITE
ce80: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
ce90: 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b E_FCNTL_ROLLBACK
cea0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f _ATOMIC_WRITE] o
ceb0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c pcode causes all
cec0: 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 write.** operat
ced0: 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 ions since the p
cee0: 72 65 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 revious successf
cef0: 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b ul call to .** [
cf00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 SQLITE_FCNTL_BEG
cf10: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d IN_ATOMIC_WRITE]
cf20: 20 74 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 to be rolled ba
cf30: 63 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c ck..** ^This fil
cf40: 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 20 e control takes
cf50: 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 the file descrip
cf60: 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 tor out of batch
cf70: 20 77 72 69 74 65 20 6d 6f 64 65 0a 2a 2a 20 73 write mode.** s
cf80: 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65 o that all subse
cf90: 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72 quent write oper
cfa0: 61 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 ations are indep
cfb0: 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 endent..** ^SQLi
cfc0: 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e te will never in
cfd0: 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 voke SQLITE_FCNT
cfe0: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 L_ROLLBACK_ATOMI
cff0: 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a C_WRITE without.
d000: 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 ** a prior succe
d010: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 ssful call to [S
d020: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 QLITE_FCNTL_BEGI
d030: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e N_ATOMIC_WRITE].
d040: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
d050: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 ITE_FCNTL_LOCK_T
d060: 49 4d 45 4f 55 54 5d 5d 0a 2a 2a 20 54 68 65 20 IMEOUT]].** The
d070: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f [SQLITE_FCNTL_LO
d080: 43 4b 5f 54 49 4d 45 4f 55 54 5d 20 6f 70 63 6f CK_TIMEOUT] opco
d090: 64 65 20 63 61 75 73 65 73 20 61 74 74 65 6d 70 de causes attemp
d0a0: 74 73 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 ts to obtain.**
d0b0: 61 20 66 69 6c 65 20 6c 6f 63 6b 20 75 73 69 6e a file lock usin
d0c0: 67 20 74 68 65 20 78 4c 6f 63 6b 20 6f 72 20 78 g the xLock or x
d0d0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 73 20 ShmLock methods
d0e0: 6f 66 20 74 68 65 20 56 46 53 20 74 6f 20 77 61 of the VFS to wa
d0f0: 69 74 0a 2a 2a 20 66 6f 72 20 75 70 20 74 6f 20 it.** for up to
d100: 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 M milliseconds b
d110: 65 66 6f 72 65 20 66 61 69 6c 69 6e 67 2c 20 77 efore failing, w
d120: 68 65 72 65 20 4d 20 69 73 20 74 68 65 20 73 69 here M is the si
d130: 6e 67 6c 65 20 0a 2a 2a 20 75 6e 73 69 67 6e 65 ngle .** unsigne
d140: 64 20 69 6e 74 65 67 65 72 20 70 61 72 61 6d 65 d integer parame
d150: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ter..**.** <li>[
d160: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 [SQLITE_FCNTL_DA
d170: 54 41 5f 56 45 52 53 49 4f 4e 5d 5d 0a 2a 2a 20 TA_VERSION]].**
d180: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
d190: 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20 L_DATA_VERSION]
d1a0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
d1b0: 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 o detect changes
d1c0: 20 74 6f 0a 2a 2a 20 61 20 64 61 74 61 62 61 73 to.** a databas
d1d0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 61 72 67 e file. The arg
d1e0: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
d1f0: 65 72 20 74 6f 20 61 20 33 32 2d 62 69 74 20 75 er to a 32-bit u
d200: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e nsigned integer.
d210: 0a 2a 2a 20 54 68 65 20 22 64 61 74 61 20 76 65 .** The "data ve
d220: 72 73 69 6f 6e 22 20 66 6f 72 20 74 68 65 20 70 rsion" for the p
d230: 61 67 65 72 20 69 73 20 77 72 69 74 74 65 6e 20 ager is written
d240: 69 6e 74 6f 20 74 68 65 20 70 6f 69 6e 74 65 72 into the pointer
d250: 2e 20 20 54 68 65 0a 2a 2a 20 22 64 61 74 61 20 . The.** "data
d260: 76 65 72 73 69 6f 6e 22 20 63 68 61 6e 67 65 73 version" changes
d270: 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 63 68 whenever any ch
d280: 61 6e 67 65 20 6f 63 63 75 72 73 20 74 6f 20 74 ange occurs to t
d290: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
d2a0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c .** database fil
d2b0: 65 2c 20 65 69 74 68 65 72 20 74 68 72 6f 75 67 e, either throug
d2c0: 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 h SQL statements
d2d0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 on the same dat
d2e0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
d2f0: 69 6f 6e 20 6f 72 20 74 68 72 6f 75 67 68 20 74 ion or through t
d300: 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 6f 6d 6d ransactions comm
d310: 69 74 74 65 64 20 62 79 20 73 65 70 61 72 61 74 itted by separat
d320: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f e database.** co
d330: 6e 6e 65 63 74 69 6f 6e 73 20 70 6f 73 73 69 62 nnections possib
d340: 6c 79 20 69 6e 20 6f 74 68 65 72 20 70 72 6f 63 ly in other proc
d350: 65 73 73 65 73 2e 20 54 68 65 20 5b 73 71 6c 69 esses. The [sqli
d360: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
d370: 73 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 s()].** interfac
d380: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
d390: 20 66 69 6e 64 20 69 66 20 61 6e 79 20 64 61 74 find if any dat
d3a0: 61 62 61 73 65 20 6f 6e 20 74 68 65 20 63 6f 6e abase on the con
d3b0: 6e 65 63 74 69 6f 6e 20 68 61 73 20 63 68 61 6e nection has chan
d3c0: 67 65 64 2c 0a 2a 2a 20 62 75 74 20 74 68 61 74 ged,.** but that
d3d0: 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 70 6f interface respo
d3e0: 6e 64 73 20 74 6f 20 63 68 61 6e 67 65 73 20 6f nds to changes o
d3f0: 6e 20 54 45 4d 50 20 61 73 20 77 65 6c 6c 20 61 n TEMP as well a
d400: 73 20 4d 41 49 4e 20 61 6e 64 20 64 6f 65 73 0a s MAIN and does.
d410: 2a 2a 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 ** not provide a
d420: 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20 64 65 mechanism to de
d430: 74 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 20 tect changes to
d440: 4d 41 49 4e 20 6f 6e 6c 79 2e 20 20 41 6c 73 6f MAIN only. Also
d450: 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 , the.** [sqlite
d460: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
d470: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 )] interface res
d480: 70 6f 6e 64 73 20 74 6f 20 69 6e 74 65 72 6e 61 ponds to interna
d490: 6c 20 63 68 61 6e 67 65 73 20 6f 6e 6c 79 20 61 l changes only a
d4a0: 6e 64 0a 2a 2a 20 6f 6d 69 74 73 20 63 68 61 6e nd.** omits chan
d4b0: 67 65 73 20 6d 61 64 65 20 62 79 20 6f 74 68 65 ges made by othe
d4c0: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 r database conne
d4d0: 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 ctions. The.**
d4e0: 5b 50 52 41 47 4d 41 20 64 61 74 61 5f 76 65 72 [PRAGMA data_ver
d4f0: 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20 70 72 sion] command pr
d500: 6f 76 69 64 65 20 61 20 6d 65 63 68 61 6e 69 73 ovide a mechanis
d510: 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e m to detect chan
d520: 67 65 73 20 74 6f 0a 2a 2a 20 61 20 73 69 6e 67 ges to.** a sing
d530: 6c 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 le attached data
d540: 62 61 73 65 20 74 68 61 74 20 6f 63 63 75 72 20 base that occur
d550: 64 75 65 20 74 6f 20 6f 74 68 65 72 20 64 61 74 due to other dat
d560: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
d570: 73 2c 0a 2a 2a 20 62 75 74 20 6f 6d 69 74 73 20 s,.** but omits
d580: 63 68 61 6e 67 65 73 20 69 6d 70 6c 65 6d 65 6e changes implemen
d590: 74 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62 ted by the datab
d5a0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f ase connection o
d5b0: 6e 20 77 68 69 63 68 20 69 74 20 69 73 0a 2a 2a n which it is.**
d5c0: 20 63 61 6c 6c 65 64 2e 20 20 54 68 69 73 20 66 called. This f
d5d0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 74 ile control is t
d5e0: 68 65 20 6f 6e 6c 79 20 6d 65 63 68 61 6e 69 73 he only mechanis
d5f0: 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e m to detect chan
d600: 67 65 73 20 74 68 61 74 0a 2a 2a 20 68 61 70 70 ges that.** happ
d610: 65 6e 20 65 69 74 68 65 72 20 69 6e 74 65 72 6e en either intern
d620: 61 6c 6c 79 20 6f 72 20 65 78 74 65 72 6e 61 6c ally or external
d630: 6c 79 20 61 6e 64 20 74 68 61 74 20 61 72 65 20 ly and that are
d640: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a associated with.
d650: 2a 2a 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 ** a particular
d660: 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
d670: 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 e..** </ul>.*/.#
d680: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
d690: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 NTL_LOCKSTATE
d6a0: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 1.#d
d6b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
d6c0: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TL_GET_LOCKPROXY
d6d0: 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65 FILE 2.#de
d6e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
d6f0: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 L_SET_LOCKPROXYF
d700: 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66 ILE 3.#def
d710: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
d720: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 _LAST_ERRNO
d730: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 4.#defi
d740: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
d750: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 SIZE_HINT
d760: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 5.#defin
d770: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 e SQLITE_FCNTL_C
d780: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 HUNK_SIZE
d790: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 6.#define
d7a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 SQLITE_FCNTL_FI
d7b0: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 LE_POINTER
d7c0: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 7.#define
d7d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e SQLITE_FCNTL_SYN
d7e0: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 C_OMITTED
d7f0: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 8.#define S
d800: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 QLITE_FCNTL_WIN3
d810: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 2_AV_RETRY
d820: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 9.#define SQ
d830: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 LITE_FCNTL_PERSI
d840: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 ST_WAL
d850: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 10.#define SQL
d860: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 ITE_FCNTL_OVERWR
d870: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ITE
d880: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 11.#define SQLI
d890: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 TE_FCNTL_VFSNAME
d8a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
d8b0: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 12.#define SQLIT
d8c0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 E_FCNTL_POWERSAF
d8d0: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 E_OVERWRITE 1
d8e0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
d8f0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 _FCNTL_PRAGMA
d900: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 14
d910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d920: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 FCNTL_BUSYHANDLE
d930: 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a R 15.
d940: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
d950: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d CNTL_TEMPFILENAM
d960: 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 E 16.#
d970: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
d980: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 NTL_MMAP_SIZE
d990: 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 18.#d
d9a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
d9b0: 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 TL_TRACE
d9c0: 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 19.#de
d9d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
d9e0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 L_HAS_MOVED
d9f0: 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 20.#def
da00: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
da10: 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 _SYNC
da20: 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 21.#defi
da30: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
da40: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 COMMIT_PHASETWO
da50: 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 22.#defin
da60: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 e SQLITE_FCNTL_W
da70: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 IN32_SET_HANDLE
da80: 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 23.#define
da90: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 SQLITE_FCNTL_WA
daa0: 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 L_BLOCK
dab0: 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20 24.#define
dac0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 SQLITE_FCNTL_ZIP
dad0: 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20 20 VFS
dae0: 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53 25.#define S
daf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 QLITE_FCNTL_RBU
db00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
db10: 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51 26.#define SQ
db20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 LITE_FCNTL_VFS_P
db30: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 OINTER
db40: 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 27.#define SQL
db50: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 ITE_FCNTL_JOURNA
db60: 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 L_POINTER
db70: 20 32 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 28.#define SQLI
db80: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 TE_FCNTL_WIN32_G
db90: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 ET_HANDLE
dba0: 32 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 29.#define SQLIT
dbb0: 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 E_FCNTL_PDB
dbc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 3
dbd0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
dbe0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f _FCNTL_BEGIN_ATO
dbf0: 4d 49 43 5f 57 52 49 54 45 20 20 20 20 20 33 31 MIC_WRITE 31
dc00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
dc10: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f FCNTL_COMMIT_ATO
dc20: 4d 49 43 5f 57 52 49 54 45 20 20 20 20 33 32 0a MIC_WRITE 32.
dc30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
dc40: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 CNTL_ROLLBACK_AT
dc50: 4f 4d 49 43 5f 57 52 49 54 45 20 20 33 33 0a 23 OMIC_WRITE 33.#
dc60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
dc70: 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 NTL_LOCK_TIMEOUT
dc80: 20 20 20 20 20 20 20 20 20 20 20 33 34 0a 23 64 34.#d
dc90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
dca0: 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 20 TL_DATA_VERSION
dcb0: 20 20 20 20 20 20 20 20 20 20 33 35 0a 23 64 65 35.#de
dcc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
dcd0: 4c 5f 53 49 5a 45 5f 4c 49 4d 49 54 20 20 20 20 L_SIZE_LIMIT
dce0: 20 20 20 20 20 20 20 20 20 33 36 0a 0a 2f 2a 20 36../*
dcf0: 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 deprecated names
dd00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
dd10: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TE_GET_LOCKPROXY
dd20: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 FILE SQLITE
dd30: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 _FCNTL_GET_LOCKP
dd40: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 ROXYFILE.#define
dd50: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b SQLITE_SET_LOCK
dd60: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 PROXYFILE S
dd70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f QLITE_FCNTL_SET_
dd80: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 LOCKPROXYFILE.#d
dd90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 efine SQLITE_LAS
dda0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 T_ERRNO
ddb0: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c SQLITE_FCNTL
ddc0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a _LAST_ERRNO.../*
ddd0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 .** CAPI3REF: Mu
dde0: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a tex Handle.**.**
ddf0: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c The mutex modul
de00: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 e within SQLite
de10: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 defines [sqlite3
de20: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e _mutex] to be an
de30: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 .** abstract typ
de40: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 e for a mutex ob
de50: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 ject. The SQLit
de60: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f e core never loo
de70: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 ks.** at the int
de80: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 ernal representa
de90: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 tion of an [sqli
dea0: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 te3_mutex]. It
deb0: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 only.** deals wi
dec0: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 th pointers to t
ded0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
dee0: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a x] object..**.**
def0: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 Mutexes are cre
df00: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ated using [sqli
df10: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 te3_mutex_alloc(
df20: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 )]..*/.typedef s
df30: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 truct sqlite3_mu
df40: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 tex sqlite3_mute
df50: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 x;../*.** CAPI3R
df60: 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 EF: Loadable Ext
df70: 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a ension Thunk.**.
df80: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** A pointer to
df90: 74 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74 the opaque sqlit
dfa0: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 e3_api_routines
dfb0: 73 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73 structure is pas
dfc0: 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 sed as.** the th
dfd0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
dfe0: 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 entry points of
dff0: 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e [loadable exten
e000: 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a sions]. This.**
e010: 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 structure must
e020: 62 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20 be typedefed in
e030: 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 order to work ar
e040: 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 ound compiler wa
e050: 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d rnings.** on som
e060: 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a e platforms..*/.
e070: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
e080: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 qlite3_api_routi
e090: 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f nes sqlite3_api_
e0a0: 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a routines;../*.**
e0b0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e CAPI3REF: OS In
e0c0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a terface Object.*
e0d0: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
e0e0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
e0f0: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e vfs object defin
e100: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
e110: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 between.** the
e120: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 SQLite core and
e130: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f the underlying o
e140: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e perating system.
e150: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 The "vfs".** i
e160: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
e170: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 e object stands
e180: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c for "virtual fil
e190: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a e system". See.
e1a0: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 ** the [VFS | VF
e1b0: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d S documentation]
e1c0: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 for further inf
e1d0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
e1e0: 54 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63 The VFS interfac
e1f0: 65 20 69 73 20 73 6f 6d 65 74 69 6d 65 73 20 65 e is sometimes e
e200: 78 74 65 6e 64 65 64 20 62 79 20 61 64 64 69 6e xtended by addin
e210: 67 20 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e g new methods on
e220: 74 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20 to.** the end.
e230: 45 61 63 68 20 74 69 6d 65 20 73 75 63 68 20 61 Each time such a
e240: 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75 n extension occu
e250: 72 73 2c 20 74 68 65 20 69 56 65 72 73 69 6f 6e rs, the iVersion
e260: 20 66 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 field.** is inc
e270: 72 65 6d 65 6e 74 65 64 2e 20 20 54 68 65 20 69 remented. The i
e280: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 73 74 Version value st
e290: 61 72 74 65 64 20 6f 75 74 20 61 73 20 31 20 69 arted out as 1 i
e2a0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 n.** SQLite [ver
e2b0: 73 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b sion 3.5.0] on [
e2c0: 64 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 dateof:3.5.0], t
e2d0: 68 65 6e 20 69 6e 63 72 65 61 73 65 64 20 74 6f hen increased to
e2e0: 20 32 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69 74 2.** with SQLit
e2f0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30 e [version 3.7.0
e300: 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 ] on [dateof:3.7
e310: 2e 30 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e .0], and then in
e320: 63 72 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20 creased.** to 3
e330: 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72 with SQLite [ver
e340: 73 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b sion 3.7.6] on [
e350: 64 61 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 dateof:3.7.6].
e360: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 Additional field
e370: 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 70 70 65 s.** may be appe
e380: 6e 64 65 64 20 74 6f 20 74 68 65 20 73 71 6c 69 nded to the sqli
e390: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 61 te3_vfs object a
e3a0: 6e 64 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 nd the iVersion
e3b0: 76 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 value.** may inc
e3c0: 72 65 61 73 65 20 61 67 61 69 6e 20 69 6e 20 66 rease again in f
e3d0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
e3e0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 f SQLite..** Not
e3f0: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 e that the struc
e400: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 ture.** of the s
e410: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 qlite3_vfs objec
e420: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 t changes in the
e430: 20 74 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d transition from
e440: 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 .** SQLite [vers
e450: 69 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 ion 3.5.9] to [v
e460: 65 72 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e ersion 3.6.0] on
e470: 20 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a [dateof:3.6.0].
e480: 2a 2a 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 ** and yet the i
e490: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 Version field wa
e4a0: 73 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a s not modified..
e4b0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 **.** The szOsFi
e4c0: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 le field is the
e4d0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 size of the subc
e4e0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f lassed [sqlite3_
e4f0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 file].** structu
e500: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 re used by this
e510: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 VFS. mxPathname
e520: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 is the maximum
e530: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 length of.** a p
e540: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 athname in this
e550: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 VFS..**.** Regis
e560: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 tered sqlite3_vf
e570: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 s objects are ke
e580: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c pt on a linked l
e590: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a ist formed by.**
e5a0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 the pNext point
e5b0: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 er. The [sqlite
e5c0: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 3_vfs_register()
e5d0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
e5e0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 3_vfs_unregister
e5f0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d ()] interfaces m
e600: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a anage this list.
e610: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 ** in a thread-s
e620: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 afe way. The [s
e630: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 qlite3_vfs_find(
e640: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 )] interface.**
e650: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 searches the lis
e660: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 t. Neither the
e670: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 application code
e680: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 nor the VFS.**
e690: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 implementation s
e6a0: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e hould use the pN
e6b0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ext pointer..**.
e6c0: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 ** The pNext fie
e6d0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 ld is the only f
e6e0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 ield in the sqli
e6f0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 te3_vfs.** struc
e700: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 ture that SQLite
e710: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 will ever modif
e720: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 y. SQLite will
e730: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f only access.** o
e740: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 r modify this fi
e750: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e eld while holdin
e760: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 g a particular s
e770: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 tatic mutex..**
e780: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
e790: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 should never mod
e7a0: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 ify anything wit
e7b0: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f hin the sqlite3_
e7c0: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e vfs.** object on
e7d0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 ce the object ha
e7e0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 s been registere
e7f0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 d..**.** The zNa
e800: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 me field holds t
e810: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 he name of the V
e820: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 FS module. The
e830: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 name must.** be
e840: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c unique across al
e850: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a l VFS modules..*
e860: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 *.** [[sqlite3_v
e870: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 fs.xOpen]].** ^S
e880: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 QLite guarantees
e890: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e that the zFilen
e8a0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f ame parameter to
e8b0: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 xOpen.** is eit
e8c0: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 her a NULL point
e8d0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 er or string obt
e8e0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 ained.** from xF
e8f0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 ullPathname() wi
e900: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 th an optional s
e910: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 uffix added..**
e920: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 ^If a suffix is
e930: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 added to the zFi
e940: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
e950: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e , it will.** con
e960: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 sist of a single
e970: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 "-" character f
e980: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f ollowed by no mo
e990: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c re than.** 11 al
e9a0: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f phanumeric and/o
e9b0: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 r "-" characters
e9c0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 ..** ^SQLite fur
e9d0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 ther guarantees
e9e0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 that.** the stri
e9f0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 ng will be valid
ea00: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 and unchanged u
ea10: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 ntil xClose() is
ea20: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 .** called. Beca
ea30: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 use of the previ
ea40: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a ous sentence,.**
ea50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
ea60: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 le] can safely s
ea70: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 tore a pointer t
ea80: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d o the.** filenam
ea90: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f e if it needs to
eaa0: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 remember the fi
eab0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 lename for some
eac0: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 reason..** If th
ead0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 e zFilename para
eae0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 meter to xOpen i
eaf0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
eb00: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d then xOpen.** m
eb10: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f ust invent its o
eb20: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d wn temporary nam
eb30: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 e for the file.
eb40: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a ^Whenever the .
eb50: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 ** xFilename par
eb60: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 ameter is NULL i
eb70: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 t will also be t
eb80: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 he case that the
eb90: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 .** flags parame
eba0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 ter will include
ebb0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
ebc0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a LETEONCLOSE]..**
ebd0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 .** The flags ar
ebe0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 gument to xOpen(
ebf0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 ) includes all b
ec00: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 its set in.** th
ec10: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
ec20: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
ec30: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 n_v2()]. Or if
ec40: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
ec50: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
ec60: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 open16()] is use
ec70: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e d, then flags in
ec80: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a cludes at least.
ec90: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
eca0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 READWRITE] | [SQ
ecb0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
ecc0: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 ]. .** If xOpen(
ecd0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 ) opens a file r
ece0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 ead-only then it
ecf0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 sets *pOutFlags
ed00: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b to.** include [
ed10: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
ed20: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 ONLY]. Other bi
ed30: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 ts in *pOutFlags
ed40: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a may be set..**.
ed50: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c ** ^(SQLite will
ed60: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 also add one of
ed70: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 the following f
ed80: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 lags to the xOpe
ed90: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 n().** call, dep
eda0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 ending on the ob
edb0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 ject being opene
edc0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a d:.**.** <ul>.**
edd0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
ede0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 PEN_MAIN_DB].**
edf0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
ee00: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d EN_MAIN_JOURNAL]
ee10: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
ee20: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a E_OPEN_TEMP_DB].
ee30: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
ee40: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e _OPEN_TEMP_JOURN
ee50: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
ee60: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 LITE_OPEN_TRANSI
ee70: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 ENT_DB].** <li>
ee80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 [SQLITE_OPEN_SU
ee90: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 BJOURNAL].** <li
eea0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
eeb0: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a MASTER_JOURNAL].
eec0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
eed0: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f _OPEN_WAL].** </
eee0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ul>)^.**.** The
eef0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 file I/O impleme
ef00: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 ntation can use
ef10: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 the object type
ef20: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e flags to.** chan
ef30: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 ge the way it de
ef40: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 als with files.
ef50: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e For example, an
ef60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 application.**
ef70: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 that does not ca
ef80: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 re about crash r
ef90: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 ecovery or rollb
efa0: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a ack might make.*
efb0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 * the open of a
efc0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e journal file a n
efd0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f o-op. Writes to
efe0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f this journal wo
eff0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e uld.** also be n
f000: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 o-ops, and any a
f010: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 ttempt to read t
f020: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 he journal would
f030: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 return.** SQLIT
f040: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 E_IOERR. Or the
f050: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
f060: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 might recognize
f070: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a that a database.
f080: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 ** file will be
f090: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e doing page-align
f0a0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 ed sector reads
f0b0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 and writes in a
f0c0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 random.** order
f0d0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 and set up its I
f0e0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 /O subsystem acc
f0f0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ordingly..**.**
f100: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 SQLite might als
f110: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 o add one of the
f120: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 following flags
f130: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 to the xOpen me
f140: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e thod:.**.** <ul>
f150: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
f160: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
f170: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 OSE].** <li> [SQ
f180: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 LITE_OPEN_EXCLUS
f190: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a IVE].** </ul>.**
f1a0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
f1b0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
f1c0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 SE] flag means t
f1d0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 he file should b
f1e0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 e.** deleted whe
f1f0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 n it is closed.
f200: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 ^The [SQLITE_OP
f210: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
f220: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 ].** will be set
f230: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 for TEMP databa
f240: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f ses and their jo
f250: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e urnals, transien
f260: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 t.** databases,
f270: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e and subjournals.
f280: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c .**.** ^The [SQL
f290: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
f2a0: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 VE] flag is alwa
f2b0: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 ys used in conju
f2c0: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 nction.** with t
f2d0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
f2e0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 CREATE] flag, wh
f2f0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 ich are both dir
f300: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f ectly.** analogo
f310: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c us to the O_EXCL
f320: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 and O_CREAT fla
f330: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 gs of the POSIX
f340: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 open().** API.
f350: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f The SQLITE_OPEN_
f360: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 EXCLUSIVE flag,
f370: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 when paired with
f380: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f the .** SQLITE_
f390: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 OPEN_CREATE, is
f3a0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 used to indicate
f3b0: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c that file shoul
f3c0: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 d always.** be c
f3d0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 reated, and that
f3e0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 it is an error
f3f0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 if it already ex
f400: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c ists..** It is <
f410: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 i>not</i> used t
f420: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 o indicate the f
f430: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 ile should be op
f440: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 ened .** for exc
f450: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a lusive access..*
f460: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 *.** ^At least s
f470: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 zOsFile bytes of
f480: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f memory are allo
f490: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a cated by SQLite.
f4a0: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 ** to hold the
f4b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 [sqlite3_file] s
f4c0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 tructure passed
f4d0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 as the third.**
f4e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 argument to xOpe
f4f0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 n. The xOpen me
f500: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 thod does not ha
f510: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 ve to.** allocat
f520: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b e the structure;
f530: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 it should just
f540: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 fill it in. Not
f550: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f e that.** the xO
f560: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 pen method must
f570: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f set the sqlite3_
f580: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f file.pMethods to
f590: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c either.** a val
f5a0: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d id [sqlite3_io_m
f5b0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f ethods] object o
f5c0: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 r to NULL. xOpe
f5d0: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 n must do.** thi
f5e0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 s even if the op
f5f0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 en fails. SQLit
f600: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 e expects that t
f610: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e he sqlite3_file.
f620: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d pMethods.** elem
f630: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 ent will be vali
f640: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 d after xOpen re
f650: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 turns regardless
f660: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a of the success.
f670: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 ** or failure of
f680: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e the xOpen call.
f690: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 .**.** [[sqlite3
f6a0: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a _vfs.xAccess]].*
f6b0: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 * ^The flags arg
f6c0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 ument to xAccess
f6d0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 () may be [SQLIT
f6e0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d E_ACCESS_EXISTS]
f6f0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 .** to test for
f700: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 the existence of
f710: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c a file, or [SQL
f720: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
f730: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 RITE] to.** test
f740: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 whether a file
f750: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 is readable and
f760: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 writable, or [SQ
f770: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
f780: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 ].** to test whe
f790: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 ther a file is a
f7a0: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 t least readable
f7b0: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e . The file can
f7c0: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f be a.** directo
f7d0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 ry..**.** ^SQLit
f7e0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c e will always al
f7f0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 locate at least
f800: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 mxPathname+1 byt
f810: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 es for the.** ou
f820: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c tput buffer xFul
f830: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 lPathname. The
f840: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 exact size of th
f850: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a e output buffer.
f860: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 ** is also passe
f870: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 d as a parameter
f880: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 to both method
f890: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 s. If the output
f8a0: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f buffer.** is no
f8b0: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 t large enough,
f8c0: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e [SQLITE_CANTOPEN
f8d0: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 ] should be retu
f8e0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 rned. Since this
f8f0: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 is.** handled a
f900: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 s a fatal error
f910: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 by SQLite, vfs i
f920: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 mplementations s
f930: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a hould endeavor.*
f940: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 * to prevent thi
f950: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 s by setting mxP
f960: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 athname to a suf
f970: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 ficiently large
f980: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 value..**.** The
f990: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 xRandomness(),
f9a0: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 xSleep(), xCurre
f9b0: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 ntTime(), and xC
f9c0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 urrentTimeInt64(
f9d0: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 ).** interfaces
f9e0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 are not strictly
f9f0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 a part of the f
fa00: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 ilesystem, but t
fa10: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 hey are.** inclu
fa20: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 ded in the VFS s
fa30: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d tructure for com
fa40: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 pleteness..** Th
fa50: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 e xRandomness()
fa60: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 function attempt
fa70: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 s to return nByt
fa80: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 es bytes.** of g
fa90: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 ood-quality rand
faa0: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 omness into zOut
fab0: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 . The return va
fac0: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 lue is.** the ac
fad0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 tual number of b
fae0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 ytes of randomne
faf0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 ss obtained..**
fb00: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 The xSleep() met
fb10: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 hod causes the c
fb20: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f alling thread to
fb30: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a sleep for at.**
fb40: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 least the numbe
fb50: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 r of microsecond
fb60: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 s given. ^The x
fb70: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a CurrentTime().**
fb80: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
fb90: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d a Julian Day Num
fba0: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 ber for the curr
fbb0: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d ent date and tim
fbc0: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 e as.** a floati
fbd0: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a ng point value..
fbe0: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 ** ^The xCurrent
fbf0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 TimeInt64() meth
fc00: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 od returns, as a
fc10: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a n integer, the J
fc20: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d ulian.** Day Num
fc30: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 ber multiplied b
fc40: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 y 86400000 (the
fc50: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 number of millis
fc60: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 econds in .** a
fc70: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 24-hour day). .
fc80: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 ** ^SQLite will
fc90: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 use the xCurrent
fca0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 TimeInt64() meth
fcb0: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 od to get the cu
fcc0: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e rrent.** date an
fcd0: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d d time if that m
fce0: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 ethod is availab
fcf0: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 le (if iVersion
fd00: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 is 2 or .** grea
fd10: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 ter and the func
fd20: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 tion pointer is
fd30: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 not NULL) and wi
fd40: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 ll fall back.**
fd50: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 to xCurrentTime(
fd60: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d ) if xCurrentTim
fd70: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 eInt64() is unav
fd80: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e ailable..**.** ^
fd90: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 The xSetSystemCa
fda0: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d ll(), xGetSystem
fdb0: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 Call(), and xNes
fdc0: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e tSystemCall() in
fdd0: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 terfaces.** are
fde0: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 not used by the
fdf0: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 SQLite core. Th
fe00: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 ese optional int
fe10: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 erfaces are prov
fe20: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 ided.** by some
fe30: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 VFSes to facilit
fe40: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 ate testing of t
fe50: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 he VFS code. By
fe60: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 overriding .** s
fe70: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 ystem calls with
fe80: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 functions under
fe90: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 its control, a
fea0: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e test program can
feb0: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 .** simulate fau
fec0: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f lts and error co
fed0: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f nditions that wo
fee0: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 uld otherwise be
fef0: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 difficult.** or
ff00: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 impossible to i
ff10: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 nduce. The set
ff20: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 of system calls
ff30: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 that can be over
ff40: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 ridden.** varies
ff50: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f from one VFS to
ff60: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 another, and fr
ff70: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f om one version o
ff80: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 f the same VFS t
ff90: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 o the.** next.
ffa0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
ffb0: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 t use these inte
ffc0: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 rfaces must be p
ffd0: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a repared for any.
ffe0: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 ** or all of the
fff0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f se interfaces to
10000 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 be NULL or for
10010 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 their behavior t
10020 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d o change.** from
10030 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 one release to
10040 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 the next. Appli
10050 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 cations must not
10060 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 attempt to acce
10070 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 ss.** any of the
10080 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 se methods if th
10090 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 e iVersion of th
100a0 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 e VFS is less th
100b0 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 an 3..*/.typedef
100c0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
100d0 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b vfs sqlite3_vfs;
100e0 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a .typedef void (*
100f0 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f sqlite3_syscall_
10100 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 ptr)(void);.stru
10110 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b ct sqlite3_vfs {
10120 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b . int iVersion;
10130 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
10140 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e tructure version
10150 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 number (current
10160 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 ly 3) */. int s
10170 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 zOsFile;
10180 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 /* Size of s
10190 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 ubclassed sqlite
101a0 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 3_file */. int
101b0 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 mxPathname;
101c0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
101d0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 file pathname le
101e0 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 ngth */. sqlite
101f0 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 3_vfs *pNext;
10200 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 /* Next regis
10210 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 tered VFS */. c
10220 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
10230 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 ; /* Name
10240 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 of this virtual
10250 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 file system */.
10260 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b void *pAppData;
10270 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 /* Poi
10280 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 nter to applicat
10290 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 ion-specific dat
102a0 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 a */. int (*xOp
102b0 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a en)(sqlite3_vfs*
102c0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
102d0 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c ame, sqlite3_fil
102e0 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 e*,.
102f0 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e int flags, in
10300 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 t *pOutFlags);.
10310 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 int (*xDelete)(
10320 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
10330 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
10340 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 int syncDir);.
10350 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 int (*xAccess)(
10360 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
10370 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
10380 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 int flags, int
10390 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 *pResOut);. int
103a0 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 (*xFullPathname
103b0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
103c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
103d0 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 e, int nOut, cha
103e0 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 r *zOut);. void
103f0 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c *(*xDlOpen)(sql
10400 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
10410 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 char *zFilename
10420 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 );. void (*xDlE
10430 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 rror)(sqlite3_vf
10440 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 s*, int nByte, c
10450 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 har *zErrMsg);.
10460 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d void (*(*xDlSym
10470 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 )(sqlite3_vfs*,v
10480 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 oid*, const char
10490 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 *zSymbol))(void
104a0 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 );. void (*xDlC
104b0 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 lose)(sqlite3_vf
104c0 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e s*, void*);. in
104d0 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 t (*xRandomness)
104e0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
104f0 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a nt nByte, char *
10500 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 zOut);. int (*x
10510 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 Sleep)(sqlite3_v
10520 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 fs*, int microse
10530 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a conds);. int (*
10540 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 xCurrentTime)(sq
10550 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 lite3_vfs*, doub
10560 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 le*);. int (*xG
10570 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c etLastError)(sql
10580 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 ite3_vfs*, int,
10590 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 char *);. /*.
105a0 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 ** The methods a
105b0 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 bove are in vers
105c0 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c ion 1 of the sql
105d0 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 ite_vfs object.
105e0 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 ** definition.
105f0 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c Those that foll
10600 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 ow are added in
10610 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 version 2 or lat
10620 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a er. */. int (*
10630 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 xCurrentTimeInt6
10640 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 4)(sqlite3_vfs*,
10650 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 sqlite3_int64*)
10660 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 ;. /*. ** The
10670 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 methods above ar
10680 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 e in versions 1
10690 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c and 2 of the sql
106a0 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a ite_vfs object..
106b0 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 ** Those below
106c0 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e are for version
106d0 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 3 and greater..
106e0 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 */. int (*xSe
106f0 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c tSystemCall)(sql
10700 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
10710 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 char *zName, sq
10720 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 lite3_syscall_pt
10730 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 r);. sqlite3_sy
10740 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 scall_ptr (*xGet
10750 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 SystemCall)(sqli
10760 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
10770 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 char *zName);.
10780 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e const char *(*xN
10790 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 extSystemCall)(s
107a0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
107b0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b st char *zName);
107c0 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d . /*. ** The m
107d0 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
107e0 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 in versions 1 t
107f0 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 hrough 3 of the
10800 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 sqlite_vfs objec
10810 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c t.. ** New fiel
10820 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 ds may be append
10830 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 ed in future ver
10840 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 sions. The iVer
10850 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 sion. ** value
10860 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 will increment w
10870 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 henever this hap
10880 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a pens. . */.};..
10890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
108a0 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 Flags for the xA
108b0 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 ccess VFS method
108c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 .**.** These int
108d0 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 eger constants c
108e0 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 an be used as th
108f0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
10900 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 r to.** the xAcc
10910 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e ess method of an
10920 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
10930 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 bject. They det
10940 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b ermine.** what k
10950 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f ind of permissio
10960 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d ns the xAccess m
10970 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 ethod is looking
10980 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 for..** With SQ
10990 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 LITE_ACCESS_EXIS
109a0 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 TS, the xAccess
109b0 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 method.** simply
109c0 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 checks whether
109d0 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e the file exists.
109e0 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f .** With SQLITE_
109f0 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
10a00 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 , the xAccess me
10a10 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 thod.** checks w
10a20 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 hether the named
10a30 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f directory is bo
10a40 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 th readable and
10a50 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 writable.** (in
10a60 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 other words, if
10a70 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 files can be add
10a80 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 ed, removed, and
10a90 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a renamed within.
10aa0 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 ** the directory
10ab0 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 )..** The SQLITE
10ac0 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
10ad0 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 E constant is cu
10ae0 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c rrently used onl
10af0 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d y by the.** [tem
10b00 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 p_store_director
10b10 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 y pragma], thoug
10b20 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 h this could cha
10b30 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a nge in a future.
10b40 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 ** release of SQ
10b50 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 Lite..** With SQ
10b60 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
10b70 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 , the xAccess me
10b80 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 thod.** checks w
10b90 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 hether the file
10ba0 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 is readable. Th
10bb0 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f e SQLITE_ACCESS_
10bc0 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 READ constant is
10bd0 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e .** currently un
10be0 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 used, though it
10bf0 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e might be used in
10c00 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 a future releas
10c10 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a e of.** SQLite..
10c20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
10c30 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 E_ACCESS_EXISTS
10c40 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
10c50 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
10c60 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 RITE 1 /* Used
10c70 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f by PRAGMA temp_
10c80 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 store_directory
10c90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
10ca0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 E_ACCESS_READ
10cb0 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 2 /* Unused
10cc0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
10cd0 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 REF: Flags for t
10ce0 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 he xShmLock VFS
10cf0 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 method.**.** The
10d00 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 se integer const
10d10 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 ants define the
10d20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 various locking
10d30 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c operations.** al
10d40 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 lowed by the xSh
10d50 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 mLock method of
10d60 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
10d70 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f ods]. The.** fo
10d80 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 llowing are the
10d90 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 only legal combi
10da0 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 nations of flags
10db0 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c to the.** xShmL
10dc0 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a ock method:.**.*
10dd0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 * <ul>.** <li>
10de0 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 SQLITE_SHM_LOCK
10df0 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 | SQLITE_SHM_SHA
10e00 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c RED.** <li> SQL
10e10 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 ITE_SHM_LOCK | S
10e20 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 QLITE_SHM_EXCLUS
10e30 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c IVE.** <li> SQL
10e40 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c ITE_SHM_UNLOCK |
10e50 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 SQLITE_SHM_SHAR
10e60 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 ED.** <li> SQLI
10e70 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 TE_SHM_UNLOCK |
10e80 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 SQLITE_SHM_EXCLU
10e90 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a SIVE.** </ul>.**
10ea0 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 .** When unlocki
10eb0 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 ng, the same SHA
10ec0 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 RED or EXCLUSIVE
10ed0 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 flag must be su
10ee0 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 pplied as.** was
10ef0 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f given on the co
10f00 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b rresponding lock
10f10 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 . .**.** The xS
10f20 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 hmLock method ca
10f30 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 n transition bet
10f40 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e ween unlocked an
10f50 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 d SHARED or.** b
10f60 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 etween unlocked
10f70 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 and EXCLUSIVE.
10f80 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 It cannot transi
10f90 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 tion between SHA
10fa0 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 RED.** and EXCLU
10fb0 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 SIVE..*/.#define
10fc0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f SQLITE_SHM_UNLO
10fd0 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 CK 1.#defi
10fe0 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f ne SQLITE_SHM_LO
10ff0 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 CK 2.#de
11000 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f fine SQLITE_SHM_
11010 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 SHARED 4.#
11020 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
11030 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 M_EXCLUSIVE 8
11040 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
11050 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f : Maximum xShmLo
11060 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 ck index.**.** T
11070 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 he xShmLock meth
11080 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 od on [sqlite3_i
11090 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 o_methods] may u
110a0 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 se values.** bet
110b0 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 ween 0 and this
110c0 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 upper bound as i
110d0 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 ts "offset" argu
110e0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c ment..** The SQL
110f0 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 ite core will ne
11100 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 ver attempt to a
11110 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 cquire or releas
11120 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 e a.** lock outs
11130 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 ide of this rang
11140 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e.*/.#define SQL
11150 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 ITE_SHM_NLOCK
11160 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 8.../*.** C
11170 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c API3REF: Initial
11180 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c ize The SQLite L
11190 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 ibrary.**.** ^Th
111a0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
111b0 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 lize() routine i
111c0 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a nitializes the.*
111d0 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 * SQLite library
111e0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
111f0 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 shutdown() routi
11200 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 ne.** deallocate
11210 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 s any resources
11220 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 that were alloca
11230 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 ted by sqlite3_i
11240 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 nitialize()..**
11250 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
11260 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 re designed to a
11270 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e id in process in
11280 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 itialization and
11290 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 .** shutdown on
112a0 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 embedded systems
112b0 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 . Workstation a
112c0 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e pplications usin
112d0 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d g.** SQLite norm
112e0 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 ally do not need
112f0 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 to invoke eithe
11300 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 r of these routi
11310 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c nes..**.** A cal
11320 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 l to sqlite3_ini
11330 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 tialize() is an
11340 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c "effective" call
11350 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 if it is.** the
11360 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 first time sqli
11370 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
11380 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 is invoked duri
11390 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 ng the lifetime
113a0 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 of.** the proces
113b0 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 s, or if it is t
113c0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 he first time sq
113d0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
113e0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a () is invoked.**
113f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c following a cal
11400 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
11410 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 tdown(). ^(Only
11420 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 an effective ca
11430 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 ll.** of sqlite3
11440 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f _initialize() do
11450 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a es any initializ
11460 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 ation. All othe
11470 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 r calls.** are h
11480 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 armless no-ops.)
11490 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 ^.**.** A call t
114a0 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
114b0 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 wn() is an "effe
114c0 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 ctive" call if i
114d0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a t is the first.*
114e0 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 * call to sqlite
114f0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 3_shutdown() sin
11500 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 ce the last sqli
11510 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
11520 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 . ^(Only.** an
11530 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 effective call t
11540 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
11550 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 wn() does any de
11560 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a initialization..
11570 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c ** All other val
11580 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 id calls to sqli
11590 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 te3_shutdown() a
115a0 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f re harmless no-o
115b0 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ps.)^.**.** The
115c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
115d0 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ze() interface i
115e0 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 s threadsafe, bu
115f0 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f t sqlite3_shutdo
11600 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 wn().** is not.
11610 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 The sqlite3_shu
11620 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 tdown() interfac
11630 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 e must only be c
11640 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 alled from a.**
11650 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 single thread.
11660 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 All open [databa
11670 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 se connections]
11680 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 must be closed a
11690 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 nd all.** other
116a0 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 SQLite resources
116b0 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 must be dealloc
116c0 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e ated prior to in
116d0 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 voking.** sqlite
116e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 3_shutdown()..**
116f0 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 .** Among other
11700 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 things, ^sqlite3
11710 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 _initialize() wi
11720 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c ll invoke.** sql
11730 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 ite3_os_init().
11740 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c Similarly, ^sql
11750 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a ite3_shutdown().
11760 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 ** will invoke s
11770 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e qlite3_os_end().
11780 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
11790 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
117a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
117b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
117c0 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 success..** ^If
117d0 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c for some reason,
117e0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
117f0 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 ize() is unable
11800 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a to initialize.**
11810 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 the library (pe
11820 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 rhaps it is unab
11830 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 le to allocate a
11840 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 needed resource
11850 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 such.** as a mu
11860 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 tex) it returns
11870 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
11880 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
11890 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 TE_OK]..**.** ^T
118a0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 he sqlite3_initi
118b0 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 alize() routine
118c0 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e is called intern
118d0 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 ally by many oth
118e0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 er.** SQLite int
118f0 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 erfaces so that
11900 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 an application u
11910 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 sually does not
11920 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b need to.** invok
11930 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
11940 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e lize() directly.
11950 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b For example, [
11960 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a sqlite3_open()].
11970 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 ** calls sqlite3
11980 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f _initialize() so
11990 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
119a0 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f ary will be auto
119b0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 matically.** ini
119c0 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 tialized when [s
119d0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 qlite3_open()] i
119e0 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 s called if it h
119f0 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 as not be initia
11a00 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 lized.** already
11a10 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 . ^However, if
11a20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
11a30 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c ed with the [SQL
11a40 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 ITE_OMIT_AUTOINI
11a50 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 T].** compile-ti
11a60 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 me option, then
11a70 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 the automatic ca
11a80 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 lls to sqlite3_i
11a90 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 nitialize().** a
11aa0 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 re omitted and t
11ab0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
11ac0 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 ust call sqlite3
11ad0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 _initialize() di
11ae0 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 rectly.** prior
11af0 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 to using any oth
11b00 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
11b10 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 ace. For maximu
11b20 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a m portability,.*
11b30 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e * it is recommen
11b40 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 ded that applica
11b50 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 tions always inv
11b60 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 oke sqlite3_init
11b70 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 ialize().** dire
11b80 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 ctly prior to us
11b90 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 ing any other SQ
11ba0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 Lite interface.
11bb0 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 Future releases
11bc0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 .** of SQLite ma
11bd0 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 y require this.
11be0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
11bf0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 the behavior ex
11c00 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 hibited.** when
11c10 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
11c20 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f ed with [SQLITE_
11c30 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d OMIT_AUTOINIT] m
11c40 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a ight become the.
11c50 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 ** default behav
11c60 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 ior in some futu
11c70 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 re release of SQ
11c80 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Lite..**.** The
11c90 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
11ca0 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f ) routine does o
11cb0 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 perating-system
11cc0 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 specific.** init
11cd0 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 ialization of th
11ce0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
11cf0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f . The sqlite3_o
11d00 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 s_end().** routi
11d10 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 ne undoes the ef
11d20 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f fect of sqlite3_
11d30 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 os_init(). Typi
11d40 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 cal tasks.** per
11d50 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 formed by these
11d60 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 routines include
11d70 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 allocation or d
11d80 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f eallocation.** o
11d90 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 f static resourc
11da0 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 es, initializati
11db0 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 on of global var
11dc0 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 iables,.** setti
11dd0 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 ng up a default
11de0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f [sqlite3_vfs] mo
11df0 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 dule, or setting
11e00 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 up.** a default
11e10 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 configuration u
11e20 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f sing [sqlite3_co
11e30 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 nfig()]..**.** T
11e40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
11e50 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f hould never invo
11e60 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 ke either sqlite
11e70 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 3_os_init().** o
11e80 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 r sqlite3_os_end
11e90 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 () directly. Th
11ea0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
11eb0 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 ould only invoke
11ec0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 .** sqlite3_init
11ed0 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c ialize() and sql
11ee0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e ite3_shutdown().
11ef0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 The sqlite3_os
11f00 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 _init().** inter
11f10 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 face is called a
11f20 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 utomatically by
11f30 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
11f40 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 ze() and.** sqli
11f50 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 te3_os_end() is
11f60 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 called by sqlite
11f70 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 3_shutdown(). A
11f80 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d ppropriate.** im
11f90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f plementations fo
11fa0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 r sqlite3_os_ini
11fb0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t() and sqlite3_
11fc0 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 os_end().** are
11fd0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
11fe0 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d e when it is com
11ff0 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 piled for Unix,
12000 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 Windows, or OS/2
12010 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f ..** When [custo
12020 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 m builds | built
12030 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 for other platf
12040 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 orms].** (using
12050 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f the [SQLITE_OS_O
12060 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d THER=1] compile-
12070 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 time.** option)
12080 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
12090 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 must supply a su
120a0 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 itable implement
120b0 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c ation for.** sql
120c0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 ite3_os_init() a
120d0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nd sqlite3_os_en
120e0 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 d(). An applica
120f0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a tion-supplied.**
12100 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
12110 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e of sqlite3_os_in
12120 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f it() or sqlite3_
12130 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 os_end().** must
12140 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
12150 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 OK] on success a
12160 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 nd some other [e
12170 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a rror code] upon.
12180 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 ** failure..*/.i
12190 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 nt sqlite3_initi
121a0 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 alize(void);.int
121b0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
121c0 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c n(void);.int sql
121d0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 ite3_os_init(voi
121e0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f d);.int sqlite3_
121f0 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f os_end(void);../
12200 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
12210 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 onfiguring The S
12220 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a QLite Library.**
12230 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
12240 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 config() interfa
12250 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 ce is used to ma
12260 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 ke global config
12270 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 uration.** chang
12280 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 es to SQLite in
12290 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 order to tune SQ
122a0 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 Lite to the spec
122b0 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a ific needs of.**
122c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
122d0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 . The default c
122e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 onfiguration is
122f0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
12300 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 most.** applicat
12310 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 ions and so this
12320 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 routine is usua
12330 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 lly not necessar
12340 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f y. It is.** pro
12350 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 vided to support
12360 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f rare applicatio
12370 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 ns with unusual
12380 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e needs..**.** <b>
12390 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 The sqlite3_conf
123a0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ig() interface i
123b0 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 s not threadsafe
123c0 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f . The applicatio
123d0 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 n.** must ensure
123e0 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 that no other S
123f0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
12400 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 are invoked by
12410 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 other.** threads
12420 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 while sqlite3_c
12430 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 onfig() is runni
12440 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 ng.</b>.**.** Th
12450 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
12460 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 () interface.**
12470 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f may only be invo
12480 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 ked prior to lib
12490 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 rary initializat
124a0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ion using.** [sq
124b0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
124c0 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 ()] or after shu
124d0 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 tdown by [sqlite
124e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 3_shutdown()]..*
124f0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f * ^If sqlite3_co
12500 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 nfig() is called
12510 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f after [sqlite3_
12520 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e initialize()] an
12530 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c d before.** [sql
12540 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
12550 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 then it will re
12560 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 turn SQLITE_MISU
12570 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 SE..** Note, how
12580 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 ever, that ^sqli
12590 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e te3_config() can
125a0 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 be called as pa
125b0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 rt of the.** imp
125c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 lementation of a
125d0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
125e0 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f fined [sqlite3_o
125f0 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a s_init()]..**.**
12600 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
12610 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 ent to sqlite3_c
12620 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e onfig() is an in
12630 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 teger.** [config
12640 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 uration option]
12650 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a that determines.
12660 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 ** what property
12670 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f of SQLite is to
12680 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 be configured.
12690 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 Subsequent argu
126a0 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 ments.** vary de
126b0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b pending on the [
126c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
126d0 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 tion].** in the
126e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a first argument..
126f0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f **.** ^When a co
12700 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
12710 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 on is set, sqlit
12720 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 e3_config() retu
12730 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e rns [SQLITE_OK].
12740 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 .** ^If the opti
12750 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 on is unknown or
12760 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c SQLite is unabl
12770 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 e to set the opt
12780 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 ion.** then this
12790 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
127a0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 a non-zero [err
127b0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 or code]..*/.int
127c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
127d0 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a int, ...);../*.*
127e0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
127f0 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 igure database c
12800 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 onnections.** ME
12810 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
12820 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
12830 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 db_config() inte
12840 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
12850 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 make configurat
12860 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 ion.** changes t
12870 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f o a [database co
12880 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 nnection]. The
12890 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d interface is sim
128a0 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 ilar to.** [sqli
128b0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 te3_config()] ex
128c0 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 cept that the ch
128d0 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 anges apply to a
128e0 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 single.** [data
128f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
12900 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 (specified in t
12910 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
12920 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 t)..**.** The se
12930 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
12940 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
12950 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 ig(D,V,...) is
12960 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 the.** [SQLITE_D
12970 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
12980 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f E | configuratio
12990 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 n verb] - an int
129a0 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 eger code .** th
129b0 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 at indicates wha
129c0 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 t aspect of the
129d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
129e0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 tion] is being c
129f0 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 onfigured..** Su
12a00 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e bsequent argumen
12a10 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e ts vary dependin
12a20 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 g on the configu
12a30 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a ration verb..**.
12a40 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c ** ^Calls to sql
12a50 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
12a60 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f return SQLITE_O
12a70 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 K if and only if
12a80 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 .** the call is
12a90 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 considered succe
12aa0 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ssful..*/.int sq
12ab0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
12ac0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 sqlite3*, int op
12ad0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , ...);../*.** C
12ae0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 API3REF: Memory
12af0 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 Allocation Routi
12b00 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 nes.**.** An ins
12b10 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
12b20 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 ject defines the
12b30 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 interface betwe
12b40 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 en SQLite.** and
12b50 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 low-level memor
12b60 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 y allocation rou
12b70 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 tines..**.** Thi
12b80 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 s object is used
12b90 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 in only one pla
12ba0 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 ce in the SQLite
12bb0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 interface..** A
12bc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
12bd0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
12be0 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 object is the ar
12bf0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 gument to.** [sq
12c00 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
12c10 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 when the configu
12c20 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
12c30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
12c40 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 IG_MALLOC] or [S
12c50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
12c60 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 MALLOC]. .** By
12c70 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 creating an ins
12c80 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
12c90 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 ject.** and pass
12ca0 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 ing it to [sqlit
12cb0 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 e3_config]([SQLI
12cc0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
12cd0 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e ]).** during con
12ce0 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 figuration, an a
12cf0 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 pplication can s
12d00 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e pecify an altern
12d10 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 ative.** memory
12d20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 allocation subsy
12d30 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 stem for SQLite
12d40 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f to use for all o
12d50 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 f its.** dynamic
12d60 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a memory needs..*
12d70 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 *.** Note that S
12d80 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 QLite comes with
12d90 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d several [built-
12da0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
12db0 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 tors].** that ar
12dc0 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 e perfectly adeq
12dd0 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 uate for the ove
12de0 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 rwhelming majori
12df0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f ty of applicatio
12e00 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 ns.** and that t
12e10 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e his object is on
12e20 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 ly useful to a t
12e30 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 iny minority of
12e40 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
12e50 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 with specialized
12e60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
12e70 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e on requirements.
12e80 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 This object is
12e90 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 .** also used du
12ea0 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 ring testing of
12eb0 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 SQLite in order
12ec0 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c to specify an al
12ed0 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d ternative.** mem
12ee0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 ory allocator th
12ef0 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d at simulates mem
12f00 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 ory out-of-memor
12f10 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a y conditions in.
12f20 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 ** order to veri
12f30 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 fy that SQLite r
12f40 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c ecovers graceful
12f50 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 ly from such.**
12f60 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a conditions..**.*
12f70 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 * The xMalloc, x
12f80 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 Realloc, and xFr
12f90 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 ee methods must
12fa0 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a work like the.**
12fb0 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c malloc(), reall
12fc0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
12fd0 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 functions from t
12fe0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 he standard C li
12ff0 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 brary..** ^SQLit
13000 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 e guarantees tha
13010 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 t the second arg
13020 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 ument to.** xRea
13030 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 lloc is always a
13040 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
13050 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 by a prior call
13060 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a to xRoundup..**.
13070 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 ** xSize should
13080 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 return the alloc
13090 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d ated size of a m
130a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
130b0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f .** previously o
130c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 btained from xMa
130d0 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 lloc or xRealloc
130e0 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 . The allocated
130f0 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 size.** is alwa
13100 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 ys at least as b
13110 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 ig as the reques
13120 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 ted size but may
13130 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a be larger..**.*
13140 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d * The xRoundup m
13150 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 ethod returns wh
13160 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 at would be the
13170 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f allocated size o
13180 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c f.** a memory al
13190 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 location given a
131a0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 particular requ
131b0 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 ested size. Mos
131c0 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f t memory.** allo
131d0 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 cators round up
131e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
131f0 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 ns at least to t
13200 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 he next multiple
13210 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 .** of 8. Some
13220 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 allocators round
13230 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 up to a larger
13240 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 multiple or to a
13250 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 power of 2..**
13260 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c Every memory all
13270 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 ocation request
13280 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 coming in throug
13290 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f h [sqlite3_mallo
132a0 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 c()].** or [sqli
132b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 te3_realloc()] f
132c0 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e irst calls xRoun
132d0 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 dup. If xRoundu
132e0 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a p returns 0, .**
132f0 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 that causes the
13300 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d corresponding m
13310 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
13320 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 to fail..**.**
13330 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 The xInit method
13340 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 initializes the
13350 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
13360 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c r. For example,
13370 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c .** it might all
13380 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 ocate any requir
13390 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 e mutexes or ini
133a0 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c tialize internal
133b0 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 data.** structu
133c0 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 res. The xShutd
133d0 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e own method is in
133e0 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c voked (indirectl
133f0 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 y) by.** [sqlite
13400 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 3_shutdown()] an
13410 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 d should dealloc
13420 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 ate any resource
13430 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 s acquired.** by
13440 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 xInit. The pAp
13450 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 pData pointer is
13460 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c used as the onl
13470 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a y parameter to.*
13480 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 * xInit and xShu
13490 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c tdown..**.** SQL
134a0 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 ite holds the [S
134b0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
134c0 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 IC_MASTER] mutex
134d0 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 when it invokes
134e0 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 .** the xInit me
134f0 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e thod, so the xIn
13500 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e it method need n
13510 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 ot be threadsafe
13520 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 . The.** xShutd
13530 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e own method is on
13540 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b ly called from [
13550 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
13560 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a ()] so it does.*
13570 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 * not need to be
13580 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 threadsafe eith
13590 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 er. For all oth
135a0 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 er methods, SQLi
135b0 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 te.** holds the
135c0 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 [SQLITE_MUTEX_ST
135d0 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 ATIC_MEM] mutex
135e0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a as long as the.*
135f0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
13600 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 _MEMSTATUS] conf
13610 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
13620 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 is turned on (w
13630 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 hich.** it is by
13640 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f default) and so
13650 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 the methods are
13660 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 automatically s
13670 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f erialized..** Ho
13680 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 wever, if [SQLIT
13690 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
136a0 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c US] is disabled,
136b0 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a then the other.
136c0 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 ** methods must
136d0 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 be threadsafe or
136e0 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 else make their
136f0 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 own arrangement
13700 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 s for.** seriali
13710 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 zation..**.** SQ
13720 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 Lite will never
13730 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d invoke xInit() m
13740 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 ore than once wi
13750 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 thout an interve
13760 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 ning.** call to
13770 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a xShutdown()..*/.
13780 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
13790 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
137a0 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d ds sqlite3_mem_m
137b0 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 ethods;.struct s
137c0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
137d0 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 ds {. void *(*x
137e0 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 Malloc)(int);
137f0 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 /* Memory
13800 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 allocation funct
13810 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a ion */. void (*
13820 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 xFree)(void*);
13830 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 /* Free
13840 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 a prior allocati
13850 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a on */. void *(*
13860 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c xRealloc)(void*,
13870 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 int); /* Resize
13880 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
13890 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 /. int (*xSize)
138a0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
138b0 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 /* Return the
138c0 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f size of an allo
138d0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
138e0 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 (*xRoundup)(int)
138f0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f ; /* Ro
13900 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 und up request s
13910 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f ize to allocatio
13920 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 n size */. int
13930 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b (*xInit)(void*);
13940 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e /* In
13950 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d itialize the mem
13960 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f ory allocator */
13970 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 . void (*xShutd
13980 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 own)(void*);
13990 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a /* Deinitializ
139a0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c e the memory all
139b0 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 ocator */. void
139c0 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 *pAppData;
139d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 /* Ar
139e0 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 gument to xInit(
139f0 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 ) and xShutdown(
13a00 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ) */.};../*.** C
13a10 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
13a20 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a ration Options.*
13a30 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e * KEYWORDS: {con
13a40 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
13a50 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 n}.**.** These c
13a60 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 onstants are the
13a70 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 available integ
13a80 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e er configuration
13a90 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a options that.**
13aa0 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 can be passed a
13ab0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
13ac0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c ment to the [sql
13ad0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 ite3_config()] i
13ae0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
13af0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f New configuratio
13b00 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 n options may be
13b10 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
13b20 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
13b30 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 ite..** Existing
13b40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
13b50 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 ptions might be
13b60 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 discontinued. A
13b70 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
13b80 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 hould check the
13b90 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d return code from
13ba0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
13bb0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 ()] to make sure
13bc0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c that.** the cal
13bd0 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b l worked. The [
13be0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
13bf0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c ] interface will
13c00 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e return a.** non
13c10 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 -zero [error cod
13c20 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 e] if a disconti
13c30 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 nued or unsuppor
13c40 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ted configuratio
13c50 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 n option.** is i
13c60 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 nvoked..**.** <d
13c70 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 l>.** [[SQLITE_C
13c80 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
13c90 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f AD]] <dt>SQLITE_
13ca0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
13cb0 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e EAD</dt>.** <dd>
13cc0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
13cd0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
13ce0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 ption. ^This op
13cf0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a tion sets the.**
13d00 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
13d10 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 ] to Single-thre
13d20 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f ad. In other wo
13d30 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 rds, it disables
13d40 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 .** all mutexing
13d50 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 and puts SQLite
13d60 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 into a mode whe
13d70 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 re it can only b
13d80 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 e used.** by a s
13d90 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 ingle thread.
13da0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
13db0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
13dc0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
13dd0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
13de0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
13df0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
13e00 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e then.** it is n
13e10 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 ot possible to c
13e20 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 hange the [threa
13e30 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 ding mode] from
13e40 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 its default.** v
13e50 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 alue of Single-t
13e60 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 hread and so [sq
13e70 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
13e80 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 will return .**
13e90 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
13ea0 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 f called with th
13eb0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
13ec0 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 SINGLETHREAD.**
13ed0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
13ee0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tion.</dd>.**.**
13ef0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
13f00 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c _MULTITHREAD]] <
13f10 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
13f20 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 _MULTITHREAD</dt
13f30 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
13f40 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
13f50 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
13f60 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 ^This option se
13f70 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 ts the.** [threa
13f80 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 ding mode] to Mu
13f90 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 lti-thread. In
13fa0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 other words, it
13fb0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 disables.** mute
13fc0 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 xing on [databas
13fd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
13fe0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
13ff0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a ement] objects..
14000 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
14010 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c on is responsibl
14020 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e e for serializin
14030 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b g access to.** [
14040 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
14050 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 ions] and [prepa
14060 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e red statements].
14070 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 But other mute
14080 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c xes.** are enabl
14090 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 ed so that SQLit
140a0 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 e will be safe t
140b0 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 o use in a multi
140c0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 -threaded.** env
140d0 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 ironment as long
140e0 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 as no two threa
140f0 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 ds attempt to us
14100 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 e the same.** [d
14110 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
14120 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 on] at the same
14130 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 time. ^If SQLit
14140 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
14150 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 th.** the [SQLIT
14160 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 E_THREADSAFE | S
14170 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
14180 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =0] compile-time
14190 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 option then.**
141a0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 it is not possib
141b0 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 le to set the Mu
141c0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 lti-thread [thre
141d0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a ading mode] and.
141e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
141f0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 ig()] will retur
14200 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d n [SQLITE_ERROR]
14210 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 if called with
14220 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f the.** SQLITE_CO
14230 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 NFIG_MULTITHREAD
14240 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
14250 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ption.</dd>.**.*
14260 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
14270 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c G_SERIALIZED]] <
14280 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
14290 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e _SERIALIZED</dt>
142a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
142b0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
142c0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
142d0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 ^This option set
142e0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 s the.** [thread
142f0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 ing mode] to Ser
14300 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 ialized. In othe
14310 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 r words, this op
14320 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 tion enables.**
14330 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c all mutexes incl
14340 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 uding the recurs
14350 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f ive.** mutexes o
14360 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
14370 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 ection] and [pre
14380 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
14390 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 objects..** In
143a0 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 this mode (which
143b0 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 is the default
143c0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
143d0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
143e0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
143f0 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 FE=1]) the SQLit
14400 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 e library will i
14410 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 tself serialize
14420 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 access.** to [da
14430 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
14440 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 ns] and [prepare
14450 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f d statements] so
14460 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 that the.** app
14470 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 lication is free
14480 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 to use the same
14490 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
144a0 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a ction] or the.**
144b0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 same [prepared
144c0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 statement] in di
144d0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 fferent threads
144e0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
144f0 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 ..** ^If SQLite
14500 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
14510 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
14520 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
14530 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
14540 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
14550 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 ption then.** it
14560 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 is not possible
14570 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 to set the Seri
14580 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
14590 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b g mode] and.** [
145a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
145b0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 ] will return [S
145c0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 QLITE_ERROR] if
145d0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a called with the.
145e0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ** SQLITE_CONFIG
145f0 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 _SERIALIZED conf
14600 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
14610 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
14620 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
14630 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 LOC]] <dt>SQLITE
14640 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f _CONFIG_MALLOC</
14650 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
14660 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
14670 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 MALLOC option ta
14680 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
14690 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a ument which is .
146a0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
146b0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
146c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f he [sqlite3_mem_
146d0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
146e0 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d re..** The argum
146f0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a ent specifies.**
14700 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 alternative low
14710 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c -level memory al
14720 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
14730 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 s to be used in
14740 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 place of.** the
14750 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
14760 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 n routines built
14770 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 into SQLite.)^
14780 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a ^SQLite makes.**
14790 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 its own private
147a0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e copy of the con
147b0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c tent of the [sql
147c0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
147d0 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 ] structure.** b
147e0 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 efore the [sqlit
147f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c e3_config()] cal
14800 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a l returns.</dd>.
14810 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
14820 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d ONFIG_GETMALLOC]
14830 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
14840 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 FIG_GETMALLOC</d
14850 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 t>.** <dd> ^(The
14860 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
14870 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 ETMALLOC option
14880 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
14890 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a rgument which.**
148a0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
148b0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
148c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d the [sqlite3_mem
148d0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
148e0 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c ure..** The [sql
148f0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
14900 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 ].** structure i
14910 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 s filled with th
14920 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 e currently defi
14930 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ned memory alloc
14940 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 ation routines.)
14950 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e ^.** This option
14960 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
14970 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 overload the def
14980 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ault memory allo
14990 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e cation.** routin
149a0 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 es with a wrappe
149b0 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f r that simulatio
149c0 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ns memory alloca
149d0 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a tion failure or.
149e0 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 ** tracks memory
149f0 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d usage, for exam
14a00 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ple. </dd>.**.**
14a10 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
14a20 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 _SMALL_MALLOC]]
14a30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
14a40 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f G_SMALL_MALLOC</
14a50 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 dt>.** <dd> ^The
14a60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
14a70 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 MALL_MALLOC opti
14a80 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 on takes single
14a90 61 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 argument of.** t
14aa0 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 ype int, interpr
14ab0 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 eted as a boolea
14ac0 6e 2c 20 77 68 69 63 68 20 69 66 20 74 72 75 65 n, which if true
14ad0 20 70 72 6f 76 69 64 65 73 20 61 20 68 69 6e 74 provides a hint
14ae0 20 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68 to.** SQLite th
14af0 61 74 20 69 74 20 73 68 6f 75 6c 64 20 61 76 6f at it should avo
14b00 69 64 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 id large memory
14b10 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 69 66 20 70 allocations if p
14b20 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 ossible..** SQLi
14b30 74 65 20 77 69 6c 6c 20 72 75 6e 20 66 61 73 74 te will run fast
14b40 65 72 20 69 66 20 69 74 20 69 73 20 66 72 65 65 er if it is free
14b50 20 74 6f 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d to make large m
14b60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
14b70 73 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61 s,.** but some a
14b80 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 pplication might
14b90 20 70 72 65 66 65 72 20 74 6f 20 72 75 6e 20 73 prefer to run s
14ba0 6c 6f 77 65 72 20 69 6e 20 65 78 63 68 61 6e 67 lower in exchang
14bb0 65 20 66 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74 e for.** guarant
14bc0 65 65 73 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79 ees about memory
14bd0 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74 fragmentation t
14be0 68 61 74 20 61 72 65 20 70 6f 73 73 69 62 6c 65 hat are possible
14bf0 20 69 66 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c if large.** all
14c00 6f 63 61 74 69 6f 6e 73 20 61 72 65 20 61 76 6f ocations are avo
14c10 69 64 65 64 2e 20 20 54 68 69 73 20 68 69 6e 74 ided. This hint
14c20 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 is normally off
14c30 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ..** </dd>.**.**
14c40 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
14c50 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 _MEMSTATUS]] <dt
14c60 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
14c70 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a EMSTATUS</dt>.**
14c80 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 <dd> ^The SQLIT
14c90 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
14ca0 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 US option takes
14cb0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
14cc0 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 of type int,.**
14cd0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
14ce0 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 boolean, which
14cf0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 enables or disab
14d00 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 les the collecti
14d10 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 on of.** memory
14d20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 allocation stati
14d30 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 stics. ^(When me
14d40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
14d50 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a statistics are.*
14d60 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 * disabled, the
14d70 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 following SQLite
14d80 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f interfaces beco
14d90 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e me non-operation
14da0 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a al:.** <ul>.**
14db0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
14dc0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a _memory_used()].
14dd0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
14de0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
14df0 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e ter()].** <li>
14e00 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 [sqlite3_soft_h
14e10 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a eap_limit64()].*
14e20 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 * <li> [sqlite
14e30 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 3_status64()].**
14e40 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d </ul>)^.** ^M
14e50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
14e60 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 statistics are
14e70 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 enabled by defau
14e80 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 lt unless SQLite
14e90 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 is.** compiled
14ea0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 with [SQLITE_DEF
14eb0 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d AULT_MEMSTATUS]=
14ec0 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 0 in which case
14ed0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
14ee0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 tion statistics
14ef0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 are disabled by
14f00 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 default..** </dd
14f10 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
14f20 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d _CONFIG_SCRATCH]
14f30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
14f40 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e FIG_SCRATCH</dt>
14f50 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c .** <dd> The SQL
14f60 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
14f70 43 48 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20 CH option is no
14f80 6c 6f 6e 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20 longer used..**
14f90 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
14fa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
14fb0 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 CACHE]] <dt>SQLI
14fc0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
14fd0 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e CHE</dt>.** <dd>
14fe0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^The SQLITE_CON
14ff0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 FIG_PAGECACHE op
15000 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 tion specifies a
15010 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 memory pool.**
15020 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 that SQLite can
15030 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 use for the data
15040 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 base page cache
15050 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 with the default
15060 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 page.** cache i
15070 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 mplementation.
15080 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 .** This configu
15090 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
150a0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 a no-op if an a
150b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
150c0 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 e page.** cache
150d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
150e0 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 s loaded using t
150f0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 he [SQLITE_CONFI
15100 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e G_PCACHE2]..** ^
15110 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 There are three
15120 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c arguments to SQL
15130 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
15140 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 ACHE: A pointer
15150 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 to.** 8-byte ali
15160 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 gned memory (pMe
15170 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 m), the size of
15180 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 each page cache
15190 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e line (sz),.** an
151a0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
151b0 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e cache lines (N).
151c0 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d .** The sz argum
151d0 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 ent should be th
151e0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 e size of the la
151f0 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 rgest database p
15200 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 age.** (a power
15210 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 of two between 5
15220 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 12 and 65536) pl
15230 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 us some extra by
15240 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 tes for each.**
15250 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 page header. ^T
15260 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 he number of ext
15270 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 ra bytes needed
15280 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 by the page head
15290 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 er.** can be det
152a0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 ermined using [S
152b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
152c0 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e CHE_HDRSZ]..** ^
152d0 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 It is harmless,
152e0 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 apart from the w
152f0 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a asted memory,.**
15300 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 for the sz para
15310 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 meter to be larg
15320 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 er than necessar
15330 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 y. The pMem.**
15340 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 argument must be
15350 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 either a NULL p
15360 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e ointer or a poin
15370 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 ter to an 8-byte
15380 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 .** aligned bloc
15390 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 k of memory of a
153a0 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 t least sz*N byt
153b0 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a es, otherwise.**
153c0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 subsequent beha
153d0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
153e0 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d d..** ^When pMem
153f0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 is not NULL, SQ
15400 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 Lite will strive
15410 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f to use the memo
15420 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 ry provided.** t
15430 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 o satisfy page c
15440 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c ache needs, fall
15450 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c ing back to [sql
15460 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 ite3_malloc()] i
15470 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 f.** a page cach
15480 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 e line is larger
15490 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f than sz bytes o
154a0 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 r if all of the
154b0 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 pMem buffer.** i
154c0 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 s exhausted..**
154d0 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c ^If pMem is NULL
154e0 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 and N is non-ze
154f0 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 ro, then each da
15500 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
15510 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 n.** does an ini
15520 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 tial bulk alloca
15530 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 tion for page ca
15540 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 che memory.** fr
15550 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
15560 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 oc()] sufficient
15570 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e for N cache lin
15580 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 es if N is posit
15590 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 ive or.** of -10
155a0 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 24*N bytes if N
155b0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e is negative, . ^
155c0 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a If additional.**
155d0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f page cache memo
155e0 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 ry is needed bey
155f0 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 ond what is prov
15600 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 ided by the init
15610 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f ial.** allocatio
15620 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 n, then SQLite g
15630 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f oes to [sqlite3_
15640 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 malloc()] separa
15650 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a tely for each.**
15660 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 additional cach
15670 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a e line. </dd>.**
15680 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
15690 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 FIG_HEAP]] <dt>S
156a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
156b0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e P</dt>.** <dd> ^
156c0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
156d0 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 G_HEAP option sp
156e0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 ecifies a static
156f0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a memory buffer .
15700 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 ** that SQLite w
15710 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 ill use for all
15720 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d of its dynamic m
15730 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
15740 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 needs.** beyond
15750 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 those provided
15760 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 for by [SQLITE_C
15770 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d ONFIG_PAGECACHE]
15780 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 ..** ^The SQLITE
15790 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 _CONFIG_HEAP opt
157a0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 ion is only avai
157b0 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 lable if SQLite
157c0 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 is compiled.** w
157d0 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 ith either [SQLI
157e0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 TE_ENABLE_MEMSYS
157f0 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 3] or [SQLITE_EN
15800 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e ABLE_MEMSYS5] an
15810 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 d returns.** [SQ
15820 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 LITE_ERROR] if i
15830 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 nvoked otherwise
15840 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 ..** ^There are
15850 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 three arguments
15860 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 to SQLITE_CONFIG
15870 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 _HEAP:.** An 8-b
15880 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e yte aligned poin
15890 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 ter to the memor
158a0 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 y,.** the number
158b0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
158c0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 memory buffer,
158d0 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 and the minimum
158e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e allocation size.
158f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 .** ^If the firs
15900 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d t pointer (the m
15910 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 emory pointer) i
15920 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c s NULL, then SQL
15930 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 ite reverts.** t
15940 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 o using its defa
15950 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ult memory alloc
15960 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d ator (the system
15970 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d malloc() implem
15980 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e entation),.** un
15990 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 doing any prior
159a0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 invocation of [S
159b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
159c0 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a LOC]. ^If the.*
159d0 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 * memory pointer
159e0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 is not NULL the
159f0 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 n the alternativ
15a00 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f e memory.** allo
15a10 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 cator is engaged
15a20 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f to handle all o
15a30 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 f SQLites memory
15a40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 allocation need
15a50 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 s..** The first
15a60 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d pointer (the mem
15a70 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 ory pointer) mus
15a80 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 t be aligned to
15a90 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 an 8-byte.** bou
15aa0 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 ndary or subsequ
15ab0 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 ent behavior of
15ac0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 SQLite will be u
15ad0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 ndefined..** The
15ae0 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 minimum allocat
15af0 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 ion size is capp
15b00 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 ed at 2**12. Rea
15b10 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a sonable values.*
15b20 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 * for the minimu
15b30 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a m allocation siz
15b40 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 e are 2**5 throu
15b50 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a gh 2**8.</dd>.**
15b60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
15b70 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e FIG_MUTEX]] <dt>
15b80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
15b90 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TEX</dt>.** <dd>
15ba0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f ^(The SQLITE_CO
15bb0 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f NFIG_MUTEX optio
15bc0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
15bd0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
15be0 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 is a.** pointer
15bf0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
15c00 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
15c10 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 utex_methods] st
15c20 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 ructure..** The
15c30 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 argument specifi
15c40 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c es alternative l
15c50 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 ow-level mutex r
15c60 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 outines to be us
15c70 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 ed.** in place t
15c80 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 he mutex routine
15c90 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c s built into SQL
15ca0 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 ite.)^ ^SQLite
15cb0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a makes a copy of.
15cc0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f ** the content o
15cd0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
15ce0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 utex_methods] st
15cf0 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 ructure before t
15d00 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 he call to.** [s
15d10 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
15d20 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 returns. ^If SQ
15d30 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
15d40 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 with.** the [SQ
15d50 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 LITE_THREADSAFE
15d60 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 | SQLITE_THREADS
15d70 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 AFE=0] compile-t
15d80 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a ime option then.
15d90 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 ** the entire mu
15da0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d texing subsystem
15db0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d is omitted from
15dc0 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 the build and h
15dd0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a ence calls to.**
15de0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
15df0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c ()] with the SQL
15e00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
15e10 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
15e20 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 ption will.** re
15e30 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 turn [SQLITE_ERR
15e40 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 OR].</dd>.**.**
15e50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
15e60 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 GETMUTEX]] <dt>S
15e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
15e80 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 MUTEX</dt>.** <d
15e90 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f d> ^(The SQLITE_
15ea0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 CONFIG_GETMUTEX
15eb0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
15ec0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
15ed0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 hich.** is a poi
15ee0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
15ef0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
15f00 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
15f10 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 s] structure. T
15f20 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d he.** [sqlite3_m
15f30 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a utex_methods].**
15f40 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 structure is fi
15f50 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 lled with the cu
15f60 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 rrently defined
15f70 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 mutex routines.)
15f80 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e ^.** This option
15f90 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
15fa0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 overload the def
15fb0 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 ault mutex alloc
15fc0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 ation.** routine
15fd0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 s with a wrapper
15fe0 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d used to track m
15ff0 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 utex usage for p
16000 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 erformance.** pr
16010 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 ofiling or testi
16020 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e ng, for example.
16030 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 ^If SQLite is
16040 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
16050 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 * the [SQLITE_TH
16060 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 READSAFE | SQLIT
16070 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
16080 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
16090 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 ion then.** the
160a0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 entire mutexing
160b0 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 subsystem is omi
160c0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 tted from the bu
160d0 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 ild and hence ca
160e0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 lls to.** [sqlit
160f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 e3_config()] wit
16100 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e h the SQLITE_CON
16110 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e FIG_GETMUTEX con
16120 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
16130 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e n will.** return
16140 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e [SQLITE_ERROR].
16150 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
16160 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
16170 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 ASIDE]] <dt>SQLI
16180 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 TE_CONFIG_LOOKAS
16190 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e IDE</dt>.** <dd>
161a0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f ^(The SQLITE_CO
161b0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f NFIG_LOOKASIDE o
161c0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 ption takes two
161d0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 arguments that d
161e0 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 etermine.** the
161f0 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 default size of
16200 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
16210 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 on each [databa
16220 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a se connection]..
16230 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
16240 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 ument is the.**
16250 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f size of each loo
16260 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c kaside buffer sl
16270 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e ot and the secon
16280 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 d is the number
16290 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f of.** slots allo
162a0 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 cated to each da
162b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
162c0 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 n.)^ ^(SQLITE_C
162d0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a ONFIG_LOOKASIDE.
162e0 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 ** sets the <i>d
162f0 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 efault</i> looka
16300 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b side size. The [
16310 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
16320 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 LOOKASIDE].** op
16330 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 tion to [sqlite3
16340 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 _db_config()] ca
16350 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 n be used to cha
16360 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 nge the lookasid
16370 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 e.** configurati
16380 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c on on individual
16390 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 connections.)^
163a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
163b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
163c0 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 HE2]] <dt>SQLITE
163d0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c _CONFIG_PCACHE2<
163e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
163f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
16400 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 _PCACHE2 option
16410 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
16420 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
16430 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 .** a pointer t
16440 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 o an [sqlite3_pc
16450 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f ache_methods2] o
16460 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a bject. This obj
16470 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a ect specifies.**
16480 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 the interface t
16490 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 o a custom page
164a0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
164b0 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 tion.)^.** ^SQLi
164c0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 te makes a copy
164d0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
164e0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d pcache_methods2]
164f0 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a object.</dd>.**
16500 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
16510 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d FIG_GETPCACHE2]]
16520 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
16530 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 IG_GETPCACHE2</d
16540 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 t>.** <dd> ^(The
16550 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
16560 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e ETPCACHE2 option
16570 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
16580 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a argument which.*
16590 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 * is a pointer t
165a0 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 o an [sqlite3_pc
165b0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f ache_methods2] o
165c0 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 bject. SQLite c
165d0 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 opies of.** the
165e0 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 current page cac
165f0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
16600 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 n into that obje
16610 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a ct.)^ </dd>.**.*
16620 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
16630 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 G_LOG]] <dt>SQLI
16640 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 TE_CONFIG_LOG</d
16650 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 t>.** <dd> The S
16660 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
16670 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 option is used
16680 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 to configure the
16690 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 SQLite.** globa
166a0 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a l [error log]..*
166b0 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 * (^The SQLITE_C
166c0 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e ONFIG_LOG option
166d0 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d takes two argum
166e0 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 ents: a pointer
166f0 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e to a.** function
16700 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 with a call sig
16710 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a nature of void(*
16720 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
16730 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e t char*), .** an
16740 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 d a pointer to v
16750 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e oid. ^If the fun
16760 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 ction pointer is
16770 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 not NULL, it is
16780 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b .** invoked by [
16790 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 sqlite3_log()] t
167a0 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c o process each l
167b0 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e ogging event. ^
167c0 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 If the.** functi
167d0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 on pointer is NU
167e0 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 LL, the [sqlite3
167f0 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 _log()] interfac
16800 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f e becomes a no-o
16810 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 p..** ^The void
16820 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 pointer that is
16830 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
16840 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f ent to SQLITE_CO
16850 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 NFIG_LOG is.** p
16860 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 assed through as
16870 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
16880 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c eter to the appl
16890 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
168a0 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 logger.** functi
168b0 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 on whenever that
168c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 function is inv
168d0 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f oked. ^The seco
168e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a nd parameter to.
168f0 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 ** the logger fu
16900 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 nction is a copy
16910 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 of the first pa
16920 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 rameter to the c
16930 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 orresponding.**
16940 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 [sqlite3_log()]
16950 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 call and is inte
16960 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 nded to be a [re
16970 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e sult code] or an
16980 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 .** [extended re
16990 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 sult code]. ^Th
169a0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
169b0 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 r passed to the
169c0 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 logger is.** log
169d0 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 message after f
169e0 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 ormatting via [s
169f0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
16a00 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 )]..** The SQLit
16a10 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 e logging interf
16a20 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 ace is not reent
16a30 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 rant; the logger
16a40 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 function.** sup
16a50 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 plied by the app
16a60 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f lication must no
16a70 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c t invoke any SQL
16a80 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ite interface..*
16a90 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 * In a multi-thr
16aa0 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f eaded applicatio
16ab0 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 n, the applicati
16ac0 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 on-defined logge
16ad0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 r.** function mu
16ae0 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 st be threadsafe
16af0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b . </dd>.**.** [[
16b00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
16b10 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 I]] <dt>SQLITE_C
16b20 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 ONFIG_URI.** <dd
16b30 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f >^(The SQLITE_CO
16b40 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 NFIG_URI option
16b50 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
16b60 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 rgument of type
16b70 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a int..** If non-z
16b80 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 ero, then URI ha
16b90 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c ndling is global
16ba0 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 ly enabled. If t
16bb0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 he parameter is
16bc0 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 zero,.** then UR
16bd0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c I handling is gl
16be0 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e obally disabled.
16bf0 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c )^ ^If URI handl
16c00 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a ing is globally.
16c10 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 ** enabled, all
16c20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 filenames passed
16c30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
16c40 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f n()], [sqlite3_o
16c50 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 pen_v2()],.** [s
16c60 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
16c70 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 or.** specified
16c80 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 as part of [ATT
16c90 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 ACH] commands ar
16ca0 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 e interpreted as
16cb0 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 URIs, regardles
16cc0 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 s.** of whether
16cd0 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 or not the [SQLI
16ce0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 TE_OPEN_URI] fla
16cf0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 g is set when th
16d00 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f e database.** co
16d10 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e nnection is open
16d20 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c ed. ^If it is gl
16d30 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c obally disabled,
16d40 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a filenames are.*
16d50 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 * only interpret
16d60 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 ed as URIs if th
16d70 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 e SQLITE_OPEN_UR
16d80 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 I flag is set wh
16d90 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 en the.** databa
16da0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
16db0 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 opened. ^(By de
16dc0 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c fault, URI handl
16dd0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a ing is globally.
16de0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 ** disabled. The
16df0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d default value m
16e00 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 ay be changed by
16e10 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 compiling with
16e20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 the.** [SQLITE_U
16e30 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 SE_URI] symbol d
16e40 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 efined.)^.**.**
16e50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
16e60 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 COVERING_INDEX_S
16e70 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 CAN]] <dt>SQLITE
16e80 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 _CONFIG_COVERING
16e90 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c _INDEX_SCAN.** <
16ea0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 dd>^The SQLITE_C
16eb0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 ONFIG_COVERING_I
16ec0 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e NDEX_SCAN option
16ed0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
16ee0 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d integer.** argum
16ef0 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 ent which is int
16f00 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f erpreted as a bo
16f10 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 olean in order t
16f20 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 o enable or disa
16f30 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f ble.** the use o
16f40 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 f covering indic
16f50 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c es for full tabl
16f60 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 e scans in the q
16f70 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a uery optimizer..
16f80 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 ** ^The default
16f90 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 setting is deter
16fa0 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 mined.** by the
16fb0 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f [SQLITE_ALLOW_CO
16fc0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 VERING_INDEX_SCA
16fd0 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 N] compile-time
16fe0 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f option, or is "o
16ff0 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f n".** if that co
17000 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
17010 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a n is omitted..**
17020 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 The ability to
17030 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 disable the use
17040 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 of covering indi
17050 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 ces for full tab
17060 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 le scans.** is b
17070 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f ecause some inco
17080 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 rrectly coded le
17090 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e gacy application
170a0 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 s might malfunct
170b0 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 ion.** when the
170c0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 optimization is
170d0 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 enabled. Provid
170e0 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 ing the ability
170f0 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 to.** disable th
17100 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 e optimization a
17110 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c llows the older,
17120 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 buggy applicati
17130 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a on code to work.
17140 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 ** without chang
17150 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 e even with newe
17160 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 r versions of SQ
17170 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 Lite..**.** [[SQ
17180 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
17190 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f HE]] [[SQLITE_CO
171a0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d NFIG_GETPCACHE]]
171b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
171c0 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 ONFIG_PCACHE and
171d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
171e0 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e ETPCACHE.** <dd>
171f0 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 These options a
17200 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 re obsolete and
17210 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 should not be us
17220 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a ed by new code..
17230 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 ** They are reta
17240 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 ined for backwar
17250 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
17260 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d but are now no-
17270 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a ops..** </dd>.**
17280 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
17290 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 FIG_SQLLOG]].**
172a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
172b0 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e G_SQLLOG.** <dd>
172c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f This option is o
172d0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 nly available if
172e0 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 sqlite is compi
172f0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
17300 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 [SQLITE_ENABLE_S
17310 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 QLLOG] pre-proce
17320 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e ssor macro defin
17330 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 ed. The first ar
17340 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a gument should.**
17350 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f be a pointer to
17360 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 a function of t
17370 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 ype void(*)(void
17380 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 *,sqlite3*,const
17390 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a char*, int)..**
173a0 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 The second shou
173b0 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 ld be of type (v
173c0 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 oid*). The callb
173d0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 ack is invoked b
173e0 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a y the library.**
173f0 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 in three separa
17400 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 te circumstances
17410 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 , identified by
17420 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 the value passed
17430 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 as the.** fourt
17440 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 h parameter. If
17450 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
17460 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 eter is 0, then
17470 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
17480 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 nection.** passe
17490 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
174a0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 argument has jus
174b0 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 t been opened. T
174c0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
174d0 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 t.** points to a
174e0 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 buffer containi
174f0 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ng the name of t
17500 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 he main database
17510 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a file. If the.**
17520 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
17530 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 r is 1, then the
17540 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
17550 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 hat the third pa
17560 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 rameter.** point
17570 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 s to has just be
17580 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c en executed. Or,
17590 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 if the fourth p
175a0 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 arameter is 2, t
175b0 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 hen.** the conne
175c0 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 ction being pass
175d0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
175e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 parameter is be
175f0 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a ing closed. The.
17600 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 ** third paramet
17610 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c er is passed NUL
17620 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 L In this case.
17630 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 An example of u
17640 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e sing this.** con
17650 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
17660 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e n can be seen in
17670 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f the "test_sqllo
17680 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 g.c" source file
17690 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e in.** the canon
176a0 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 ical SQLite sour
176b0 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a ce tree.</dd>.**
176c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
176d0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a FIG_MMAP_SIZE]].
176e0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
176f0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a NFIG_MMAP_SIZE.*
17700 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f * <dd>^SQLITE_CO
17710 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 NFIG_MMAP_SIZE t
17720 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 akes two 64-bit
17730 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 integer (sqlite3
17740 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a _int64) values.*
17750 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64 * that are the d
17760 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 efault mmap size
17770 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 limit (the defa
17780 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a ult setting for.
17790 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f ** [PRAGMA mmap_
177a0 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d size]) and the m
177b0 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d aximum allowed m
177c0 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a map size limit..
177d0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 ** ^The default
177e0 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f setting can be o
177f0 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 verridden by eac
17800 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 h database conne
17810 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 ction using.** e
17820 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d ither the [PRAGM
17830 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d A mmap_size] com
17840 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e mand, or by usin
17850 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 g the.** [SQLITE
17860 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 _FCNTL_MMAP_SIZE
17870 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 ] file control.
17880 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 ^(The maximum a
17890 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 llowed mmap size
178a0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 .** will be sile
178b0 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 ntly truncated i
178c0 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 f necessary so t
178d0 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 hat it does not
178e0 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f exceed the.** co
178f0 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d mpile-time maxim
17900 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 um mmap size set
17910 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 by the.** [SQLI
17920 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 TE_MAX_MMAP_SIZE
17930 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
17940 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 ption.)^.** ^If
17950 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 either argument
17960 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 to this option i
17970 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e s negative, then
17980 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 that argument i
17990 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 s.** changed to
179a0 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 its compile-time
179b0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 default..**.**
179c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
179d0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d WIN32_HEAPSIZE]]
179e0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
179f0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 ONFIG_WIN32_HEAP
17a00 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 SIZE.** <dd>^The
17a10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 SQLITE_CONFIG_W
17a20 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 IN32_HEAPSIZE op
17a30 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 tion is only ava
17a40 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 ilable if SQLite
17a50 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 is.** compiled
17a60 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 for Windows with
17a70 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e the [SQLITE_WIN
17a80 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 32_MALLOC] pre-p
17a90 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a rocessor macro.*
17aa0 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 * defined. ^SQLI
17ab0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f TE_CONFIG_WIN32_
17ac0 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 HEAPSIZE takes a
17ad0 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 32-bit unsigned
17ae0 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a integer value.*
17af0 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 * that specifies
17b00 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a the maximum siz
17b10 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 e of the created
17b20 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 heap..**.** [[S
17b30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
17b40 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c CHE_HDRSZ]].** <
17b50 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
17b60 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a _PCACHE_HDRSZ.**
17b70 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 <dd>^The SQLITE
17b80 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 _CONFIG_PCACHE_H
17b90 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 DRSZ option take
17ba0 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d s a single param
17bb0 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 eter which.** is
17bc0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
17bd0 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 integer and wri
17be0 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e tes into that in
17bf0 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 teger the number
17c00 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 of extra.** byt
17c10 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75 es per page requ
17c20 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 ired for each pa
17c30 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f ge in [SQLITE_CO
17c40 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e NFIG_PAGECACHE].
17c50 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f .** The amount o
17c60 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65 f extra space re
17c70 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 quired can chang
17c80 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 e depending on t
17c90 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 he compiler,.**
17ca0 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c target platform,
17cb0 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 and SQLite vers
17cc0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c ion..**.** [[SQL
17cd0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a ITE_CONFIG_PMASZ
17ce0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
17cf0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a _CONFIG_PMASZ.**
17d00 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 <dd>^The SQLITE
17d10 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 _CONFIG_PMASZ op
17d20 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
17d30 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 gle parameter wh
17d40 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 ich.** is an uns
17d50 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e igned integer an
17d60 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 d sets the "Mini
17d70 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f mum PMA Size" fo
17d80 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 r the multithrea
17d90 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f ded.** sorter to
17da0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 that integer.
17db0 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 The default mini
17dc0 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 mum PMA Size is
17dd0 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 set by the.** [S
17de0 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 QLITE_SORTER_PMA
17df0 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 SZ] compile-time
17e00 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 option. New th
17e10 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 reads are launch
17e20 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 ed.** to help wi
17e30 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f th sort operatio
17e40 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 ns when multithr
17e50 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a eaded sorting.**
17e60 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 is enabled (usi
17e70 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 ng the [PRAGMA t
17e80 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 hreads] command)
17e90 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 and the amount
17ea0 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f of content.** to
17eb0 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 be sorted excee
17ec0 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 ds the page size
17ed0 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d times the minim
17ee0 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 um of the.** [PR
17ef0 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d AGMA cache_size]
17f00 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 setting and thi
17f10 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b s value..**.** [
17f20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
17f30 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a TMTJRNL_SPILL]].
17f40 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
17f50 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 NFIG_STMTJRNL_SP
17f60 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 ILL.** <dd>^The
17f70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 SQLITE_CONFIG_ST
17f80 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 MTJRNL_SPILL opt
17f90 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
17fa0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 le parameter whi
17fb0 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 ch.** becomes th
17fc0 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 e [statement jou
17fd0 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 rnal] spill-to-d
17fe0 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 isk threshold.
17ff0 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a .** [Statement j
18000 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c ournals] are hel
18010 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 d in memory unti
18020 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e l their size (in
18030 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 bytes).** excee
18040 64 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c ds this threshol
18050 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e d, at which poin
18060 74 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74 t they are writt
18070 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f en to disk..** O
18080 72 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f r if the thresho
18090 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d ld is -1, statem
180a0 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 ent journals are
180b0 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 always held.**
180c0 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d exclusively in m
180d0 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 emory..** Since
180e0 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a many statement j
180f0 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 ournals never be
18100 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 come large, sett
18110 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a ing the spill.**
18120 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 threshold to a
18130 76 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 value such as 64
18140 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 KiB can greatly
18150 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e reduce the amoun
18160 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 t of.** I/O requ
18170 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 ired to support
18180 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 statement rollba
18190 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 ck..** The defau
181a0 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 lt value for thi
181b0 73 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e s setting is con
181c0 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a trolled by the.*
181d0 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 * [SQLITE_STMTJR
181e0 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c NL_SPILL] compil
181f0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a e-time option..*
18200 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
18210 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 NFIG_SORTERREF_S
18220 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c IZE]].** <dt>SQL
18230 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 ITE_CONFIG_SORTE
18240 52 52 45 46 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 RREF_SIZE.** <dd
18250 3e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 >The SQLITE_CONF
18260 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a IG_SORTERREF_SIZ
18270 45 20 6f 70 74 69 6f 6e 20 61 63 63 65 70 74 73 E option accepts
18280 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 a single parame
18290 74 65 72 0a 2a 2a 20 6f 66 20 74 79 70 65 20 28 ter.** of type (
182a0 69 6e 74 29 20 2d 20 74 68 65 20 6e 65 77 20 76 int) - the new v
182b0 61 6c 75 65 20 6f 66 20 74 68 65 20 73 6f 72 74 alue of the sort
182c0 65 72 2d 72 65 66 65 72 65 6e 63 65 20 73 69 7a er-reference siz
182d0 65 20 74 68 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20 e threshold..**
182e0 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 53 51 Usually, when SQ
182f0 4c 69 74 65 20 75 73 65 73 20 61 6e 20 65 78 74 Lite uses an ext
18300 65 72 6e 61 6c 20 73 6f 72 74 20 74 6f 20 6f 72 ernal sort to or
18310 64 65 72 20 72 65 63 6f 72 64 73 20 61 63 63 6f der records acco
18320 72 64 69 6e 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f rding.** to an O
18330 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2c 20 RDER BY clause,
18340 61 6c 6c 20 66 69 65 6c 64 73 20 72 65 71 75 69 all fields requi
18350 72 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 red by the calle
18360 72 20 61 72 65 20 70 72 65 73 65 6e 74 20 69 6e r are present in
18370 20 74 68 65 0a 2a 2a 20 73 6f 72 74 65 64 20 72 the.** sorted r
18380 65 63 6f 72 64 73 2e 20 48 6f 77 65 76 65 72 2c ecords. However,
18390 20 69 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 if SQLite deter
183a0 6d 69 6e 65 73 20 62 61 73 65 64 20 6f 6e 20 74 mines based on t
183b0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 he declared type
183c0 0a 2a 2a 20 6f 66 20 61 20 74 61 62 6c 65 20 63 .** of a table c
183d0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 74 73 20 76 olumn that its v
183e0 61 6c 75 65 73 20 61 72 65 20 6c 69 6b 65 6c 79 alues are likely
183f0 20 74 6f 20 62 65 20 76 65 72 79 20 6c 61 72 67 to be very larg
18400 65 20 2d 20 6c 61 72 67 65 72 0a 2a 2a 20 74 68 e - larger.** th
18410 61 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 65 an the configure
18420 64 20 73 6f 72 74 65 72 2d 72 65 66 65 72 65 6e d sorter-referen
18430 63 65 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c ce size threshol
18440 64 20 2d 20 74 68 65 6e 20 61 20 72 65 66 65 72 d - then a refer
18450 65 6e 63 65 0a 2a 2a 20 69 73 20 73 74 6f 72 65 ence.** is store
18460 64 20 69 6e 20 65 61 63 68 20 73 6f 72 74 65 64 d in each sorted
18470 20 72 65 63 6f 72 64 20 61 6e 64 20 74 68 65 20 record and the
18480 72 65 71 75 69 72 65 64 20 63 6f 6c 75 6d 6e 20 required column
18490 76 61 6c 75 65 73 20 6c 6f 61 64 65 64 0a 2a 2a values loaded.**
184a0 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 from the databa
184b0 73 65 20 61 73 20 72 65 63 6f 72 64 73 20 61 72 se as records ar
184c0 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 73 6f e returned in so
184d0 72 74 65 64 20 6f 72 64 65 72 2e 20 54 68 65 20 rted order. The
184e0 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 default.** value
184f0 20 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e for this option
18500 20 69 73 20 74 6f 20 6e 65 76 65 72 20 75 73 65 is to never use
18510 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 this optimizati
18520 6f 6e 2e 20 53 70 65 63 69 66 79 69 6e 67 20 61 on. Specifying a
18530 20 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 76 61 .** negative va
18540 6c 75 65 20 66 6f 72 20 74 68 69 73 20 6f 70 74 lue for this opt
18550 69 6f 6e 20 72 65 73 74 6f 72 65 73 20 74 68 65 ion restores the
18560 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f default behavio
18570 75 72 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 ur..** This opti
18580 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c on is only avail
18590 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 able if SQLite i
185a0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
185b0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 the.** [SQLITE_E
185c0 4e 41 42 4c 45 5f 53 4f 52 54 45 52 5f 52 45 46 NABLE_SORTER_REF
185d0 45 52 45 4e 43 45 53 5d 20 63 6f 6d 70 69 6c 65 ERENCES] compile
185e0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a -time option..**
185f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
18600 46 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a FIG_MEMDB_MAXSIZ
18610 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 E]].** <dt>SQLIT
18620 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 44 42 5f 4d E_CONFIG_MEMDB_M
18630 41 58 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68 AXSIZE.** <dd>Th
18640 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
18650 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45 20 6f 70 MEMDB_MAXSIZE op
18660 74 69 6f 6e 20 61 63 63 65 70 74 73 20 61 20 73 tion accepts a s
18670 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 0a ingle parameter.
18680 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 ** [sqlite3_int6
18690 34 5d 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 4] parameter whi
186a0 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c ch is the defaul
186b0 74 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 66 t maximum size f
186c0 6f 72 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 0a or an in-memory.
186d0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 72 65 61 ** database crea
186e0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
186f0 65 33 5f 64 65 73 65 72 69 61 6c 69 7a 65 28 29 e3_deserialize()
18700 5d 2e 20 20 54 68 69 73 20 64 65 66 61 75 6c 74 ]. This default
18710 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 73 69 7a 65 maximum.** size
18720 20 63 61 6e 20 62 65 20 61 64 6a 75 73 74 65 64 can be adjusted
18730 20 75 70 20 6f 72 20 64 6f 77 6e 20 66 6f 72 20 up or down for
18740 69 6e 64 69 76 69 64 75 61 6c 20 64 61 74 61 62 individual datab
18750 61 73 65 73 20 75 73 69 6e 67 20 74 68 65 0a 2a ases using the.*
18760 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f * [SQLITE_FCNTL_
18770 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 5b 73 71 6c SIZE_LIMIT] [sql
18780 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
18790 6c 7c 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 5d 2e l|file-control].
187a0 20 20 49 66 20 74 68 69 73 0a 2a 2a 20 63 6f 6e If this.** con
187b0 66 69 67 75 72 61 74 69 6f 6e 20 73 65 74 74 69 figuration setti
187c0 6e 67 20 69 73 20 6e 65 76 65 72 20 75 73 65 64 ng is never used
187d0 2c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 , then the defau
187e0 6c 74 20 6d 61 78 69 6d 75 6d 20 69 73 20 64 65 lt maximum is de
187f0 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 termined.** by t
18800 68 65 20 5b 53 51 4c 49 54 45 5f 4d 45 4d 44 42 he [SQLITE_MEMDB
18810 5f 44 45 46 41 55 4c 54 5f 4d 41 58 53 49 5a 45 _DEFAULT_MAXSIZE
18820 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
18830 70 74 69 6f 6e 2e 20 20 49 66 20 74 68 61 74 0a ption. If that.
18840 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 ** compile-time
18850 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 74 20 73 65 option is not se
18860 74 2c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 t, then the defa
18870 75 6c 74 20 6d 61 78 69 6d 75 6d 20 69 73 20 31 ult maximum is 1
18880 30 37 33 37 34 31 38 32 34 2e 0a 2a 2a 20 3c 2f 073741824..** </
18890 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
188a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
188b0 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a GLETHREAD 1 /*
188c0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nil */.#define
188d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
188e0 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f LTITHREAD 2 /
188f0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 * nil */.#define
18900 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
18910 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 ERIALIZED 3
18920 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
18930 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
18940 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 MALLOC 4
18950 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f /* sqlite3_mem_
18960 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
18970 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
18980 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 G_GETMALLOC
18990 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 5 /* sqlite3_me
189a0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 m_methods* */.#d
189b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
189c0 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 FIG_SCRATCH
189d0 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 6 /* No longe
189e0 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e r used */.#defin
189f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
18a00 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 PAGECACHE 7
18a10 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 /* void*, int s
18a20 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 z, int N */.#def
18a30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
18a40 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 G_HEAP
18a50 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 8 /* void*, int
18a60 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 nByte, int min
18a70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18a80 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
18a90 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f US 9 /* boo
18aa0 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 lean */.#define
18ab0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
18ac0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f TEX 10 /
18ad0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f * sqlite3_mutex_
18ae0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
18af0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
18b00 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 G_GETMUTEX 1
18b10 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 1 /* sqlite3_mu
18b20 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a tex_methods* */.
18b30 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 /* previously SQ
18b40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e LITE_CONFIG_CHUN
18b50 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 KALLOC 12 which
18b60 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a is now unused. *
18b70 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 / .#define SQLIT
18b80 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
18b90 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 DE 13 /* int
18ba0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
18bb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
18bc0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f ACHE 14 /
18bd0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 * no-op */.#defi
18be0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18bf0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 _GETPCACHE 15
18c00 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 /* no-op */.#d
18c10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
18c20 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 FIG_LOG
18c30 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 16 /* xFunc, v
18c40 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 oid* */.#define
18c50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
18c60 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f I 17 /
18c70 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 * int */.#define
18c80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
18c90 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 CACHE2 18
18ca0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 /* sqlite3_pcach
18cb0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 e_methods2* */.#
18cc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
18cd0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 NFIG_GETPCACHE2
18ce0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 19 /* sqlite3
18cf0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 _pcache_methods2
18d00 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
18d10 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 ITE_CONFIG_COVER
18d20 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 ING_INDEX_SCAN 2
18d30 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 0 /* int */.#de
18d40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
18d50 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 IG_SQLLOG
18d60 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 21 /* xSqllog,
18d70 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 void* */.#define
18d80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
18d90 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 MAP_SIZE 22
18da0 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 /* sqlite3_int64
18db0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
18dc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18dd0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 E_CONFIG_WIN32_H
18de0 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 EAPSIZE 23
18df0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f /* int nByte */
18e00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18e10 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 CONFIG_PCACHE_HD
18e20 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f RSZ 24 /
18e30 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 * int *psz */.#d
18e40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
18e50 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 FIG_PMASZ
18e60 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 25 /* u
18e70 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d nsigned int szPm
18e80 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c a */.#define SQL
18e90 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a ITE_CONFIG_STMTJ
18ea0 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 RNL_SPILL 2
18eb0 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 6 /* int nByte
18ec0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18ed0 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d E_CONFIG_SMALL_M
18ee0 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20 ALLOC 27
18ef0 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 /* boolean */.#
18f00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
18f10 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 NFIG_SORTERREF_S
18f20 49 5a 45 20 20 20 20 20 20 32 38 20 20 2f 2a 20 IZE 28 /*
18f30 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 int nByte */.#de
18f40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
18f50 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45 IG_MEMDB_MAXSIZE
18f60 20 20 20 20 20 20 20 32 39 20 20 2f 2a 20 73 71 29 /* sq
18f70 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 0a lite3_int64 */..
18f80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
18f90 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
18fa0 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f ion Configuratio
18fb0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 n Options.**.**
18fc0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
18fd0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c are the availabl
18fe0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 e integer config
18ff0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
19000 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 that.** can be p
19010 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 assed as the sec
19020 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
19030 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f the [sqlite3_db_
19040 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
19050 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 ace..**.** New c
19060 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
19070 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 ions may be adde
19080 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
19090 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
190a0 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 ** Existing conf
190b0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
190c0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f s might be disco
190d0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 ntinued. Applic
190e0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
190f0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 check the retur
19100 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c n code from [sql
19110 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
19120 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 ] to make sure t
19130 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 hat.** the call
19140 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 worked. ^The [s
19150 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
19160 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 ()] interface wi
19170 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e ll return a.** n
19180 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 on-zero [error c
19190 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e ode] if a discon
191a0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 tinued or unsupp
191b0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 orted configurat
191c0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 ion option.** is
191d0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
191e0 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 <dl>.** [[SQLITE
191f0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
19200 49 44 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c IDE]].** <dt>SQL
19210 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
19220 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c KASIDE</dt>.** <
19230 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
19240 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 takes three add
19250 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
19260 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 s that determine
19270 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 the .** [lookas
19280 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ide memory alloc
19290 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 ator] configurat
192a0 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 ion for the [dat
192b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
192c0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 ]..** ^The first
192d0 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 argument (the t
192e0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
192f0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f o [sqlite3_db_co
19300 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 nfig()] is a.**
19310 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d pointer to a mem
19320 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 ory buffer to us
19330 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 e for lookaside
19340 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 memory..** ^The
19350 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 first argument a
19360 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f fter the SQLITE_
19370 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
19380 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 DE verb.** may b
19390 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 e NULL in which
193a0 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c case SQLite will
193b0 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a allocate the.**
193c0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 lookaside buffe
193d0 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b r itself using [
193e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
193f0 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 ]. ^The second a
19400 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a rgument is the.*
19410 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c * size of each l
19420 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 ookaside buffer
19430 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 slot. ^The thir
19440 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
19450 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 e number of.** s
19460 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 lots. The size
19470 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e of the buffer in
19480 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
19490 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 ent must be grea
194a0 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 ter than.** or e
194b0 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 qual to the prod
194c0 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e uct of the secon
194d0 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 d and third argu
194e0 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 ments. The buff
194f0 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c er.** must be al
19500 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 igned to an 8-by
19510 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 te boundary. ^I
19520 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 f the second arg
19530 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 ument to.** SQLI
19540 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
19550 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d ASIDE is not a m
19560 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 ultiple of 8, it
19570 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a is internally.*
19580 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 * rounded down t
19590 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c o the next small
195a0 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 er multiple of 8
195b0 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 . ^(The lookasi
195c0 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e de memory.** con
195d0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 figuration for a
195e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
195f0 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 tion can only be
19600 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 changed when th
19610 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e at.** connection
19620 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c is not currentl
19630 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 y using lookasid
19640 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 e memory, or in
19650 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 other words.** w
19660 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 hen the "current
19670 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 value" returned
19680 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f by.** [sqlite3_
19690 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 db_status](D,[SQ
196a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
196b0 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a ASIDE],...) is z
196c0 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 ero..** Any atte
196d0 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 mpt to change th
196e0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f e lookaside memo
196f0 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ry configuration
19700 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a when lookaside.
19710 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 ** memory is in
19720 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 use leaves the c
19730 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 onfiguration unc
19740 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 hanged and retur
19750 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 ns .** [SQLITE_B
19760 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a USY].)^</dd>.**.
19770 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f ** [[SQLITE_DBCO
19780 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 NFIG_ENABLE_FKEY
19790 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
197a0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
197b0 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 _FKEY</dt>.** <d
197c0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
197d0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c is used to enabl
197e0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 e or disable the
197f0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a enforcement of.
19800 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 ** [foreign key
19810 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 constraints]. T
19820 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 here should be t
19830 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 wo additional ar
19840 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 guments..** The
19850 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 first argument i
19860 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 s an integer whi
19870 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 ch is 0 to disab
19880 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e le FK enforcemen
19890 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 t,.** positive t
198a0 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f o enable FK enfo
198b0 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 rcement or negat
198c0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 ive to leave FK
198d0 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 enforcement.** u
198e0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 nchanged. The s
198f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
19900 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
19910 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 an integer into
19920 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 which.** is writ
19930 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e ten 0 or 1 to in
19940 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 dicate whether F
19950 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 K enforcement is
19960 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f off or on.** fo
19970 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c llowing this cal
19980 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 l. The second p
19990 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 arameter may be
199a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
199b0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 in.** which case
199c0 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d the FK enforcem
199d0 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e ent setting is n
199e0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b ot reported back
199f0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b . </dd>.**.** [[
19a00 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
19a10 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 5d 5d ENABLE_TRIGGER]]
19a20 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
19a30 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 BCONFIG_ENABLE_T
19a40 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c RIGGER</dt>.** <
19a50 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
19a60 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 is used to enab
19a70 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 le or disable [C
19a80 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 REATE TRIGGER |
19a90 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 triggers]..** Th
19aa0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 ere should be tw
19ab0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 o additional arg
19ac0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 uments..** The f
19ad0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
19ae0 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 an integer whic
19af0 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c h is 0 to disabl
19b00 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 e triggers,.** p
19b10 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c ositive to enabl
19b20 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 e triggers or ne
19b30 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 gative to leave
19b40 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 the setting unch
19b50 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 anged..** The se
19b60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
19b70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
19b80 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 n integer into w
19b90 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 hich.** is writt
19ba0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 en 0 or 1 to ind
19bb0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 icate whether tr
19bc0 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 iggers are disab
19bd0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a led or enabled.*
19be0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 * following this
19bf0 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f call. The seco
19c00 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 nd parameter may
19c10 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 be a NULL point
19c20 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 er, in.** which
19c30 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 case the trigger
19c40 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 setting is not
19c50 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c reported back. <
19c60 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
19c70 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
19c80 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a BLE_FTS3_TOKENIZ
19c90 45 52 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 ER]].** <dt>SQLI
19ca0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
19cb0 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 LE_FTS3_TOKENIZE
19cc0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e R</dt>.** <dd> ^
19cd0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 This option is u
19ce0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 sed to enable or
19cf0 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 disable the.**
19d00 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 [fts3_tokenizer(
19d10 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63 )] function whic
19d20 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 h is part of the
19d30 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d .** [FTS3] full-
19d40 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67 69 text search engi
19d50 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a ne extension..**
19d60 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 There should be
19d70 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 two additional
19d80 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 arguments..** Th
19d90 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
19da0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 is an integer w
19db0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 hich is 0 to dis
19dc0 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 able fts3_tokeni
19dd0 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69 zer() or.** posi
19de0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66 tive to enable f
19df0 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 ts3_tokenizer()
19e00 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c or negative to l
19e10 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 eave the setting
19e20 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a .** unchanged..*
19e30 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 * The second par
19e40 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e ameter is a poin
19e50 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
19e60 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 r into which.**
19e70 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 is written 0 or
19e80 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 1 to indicate wh
19e90 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e ether fts3_token
19ea0 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 izer is disabled
19eb0 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 or enabled.** f
19ec0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 ollowing this ca
19ed0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ll. The second
19ee0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
19ef0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
19f00 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 in.** which cas
19f10 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e e the new settin
19f20 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 g is not reporte
19f30 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a d back. </dd>.**
19f40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 .** [[SQLITE_DBC
19f50 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 ONFIG_ENABLE_LOA
19f60 44 5f 45 58 54 45 4e 53 49 4f 4e 5d 5d 0a 2a 2a D_EXTENSION]].**
19f70 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
19f80 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 NFIG_ENABLE_LOAD
19f90 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a _EXTENSION</dt>.
19fa0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
19fb0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
19fc0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
19fd0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c e the [sqlite3_l
19fe0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d oad_extension()]
19ff0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e .** interface in
1a000 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 dependently of t
1a010 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 he [load_extensi
1a020 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 on()] SQL functi
1a030 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 on..** The [sqli
1a040 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f te3_enable_load_
1a050 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 extension()] API
1a060 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
1a070 62 6c 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a bles both the.**
1a080 20 43 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f C-API [sqlite3_
1a090 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
1a0a0 5d 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 ] and the SQL fu
1a0b0 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 nction [load_ext
1a0c0 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 ension()]..** Th
1a0d0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 ere should be tw
1a0e0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 o additional arg
1a0f0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 uments..** When
1a100 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
1a110 6e 74 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 nt to this inter
1a120 66 61 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20 face is 1, then
1a130 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69 only the C-API i
1a140 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 s.** enabled and
1a150 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
1a160 6e 20 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c n remains disabl
1a170 65 64 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 ed. If the firs
1a180 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a t argument to.**
1a190 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
1a1a0 69 73 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 is 0, then both
1a1b0 74 68 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 the C-API and th
1a1c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 e SQL function a
1a1d0 72 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 re disabled..**
1a1e0 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67 If the first arg
1a1f0 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 ument is -1, the
1a200 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 n no changes are
1a210 20 6d 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f made to state o
1a220 66 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 f either the.**
1a230 43 2d 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c C-API or the SQL
1a240 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 function..** Th
1a250 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
1a260 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 er is a pointer
1a270 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e to an integer in
1a280 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 to which.** is w
1a290 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f ritten 0 or 1 to
1a2a0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 indicate whethe
1a2b0 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f r [sqlite3_load_
1a2c0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 extension()] int
1a2d0 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 erface.** is dis
1a2e0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 abled or enabled
1a2f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 following this
1a300 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e call. The secon
1a310 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a d parameter may.
1a320 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 ** be a NULL poi
1a330 6e 74 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 nter, in which c
1a340 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 ase the new sett
1a350 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 ing is not repor
1a360 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 ted back..** </d
1a370 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
1a380 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 E_DBCONFIG_MAIND
1a390 42 4e 41 4d 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 BNAME]] <dt>SQLI
1a3a0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e TE_DBCONFIG_MAIN
1a3b0 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c DBNAME</dt>.** <
1a3c0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
1a3d0 20 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e is used to chan
1a3e0 67 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ge the name of t
1a3f0 68 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61 he "main" databa
1a400 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e se.** schema. ^
1a410 54 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e The sole argumen
1a420 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
1a430 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 o a constant UTF
1a440 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 8 string.** whic
1a450 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 h will become th
1a460 65 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d e new schema nam
1a470 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d e in place of "m
1a480 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a ain". ^SQLite.*
1a490 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 * does not make
1a4a0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 a copy of the ne
1a4b0 77 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 w main schema na
1a4c0 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 me string, so th
1a4d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a e application.**
1a4e0 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 must ensure tha
1a4f0 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 t the argument p
1a500 61 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20 assed into this
1a510 44 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 DBCONFIG option
1a520 69 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 is unchanged.**
1a530 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20 until after the
1a540 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1a550 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c ion closes..** <
1a560 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
1a570 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f ITE_DBCONFIG_NO_
1a580 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 5d 5d 20 CKPT_ON_CLOSE]]
1a590 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
1a5a0 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f BCONFIG_NO_CKPT_
1a5b0 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a ON_CLOSE</dt>.**
1a5c0 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 <dd> Usually, w
1a5d0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 hen a database i
1a5e0 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c n wal mode is cl
1a5f0 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 osed or detached
1a600 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 from a .** data
1a610 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c base handle, SQL
1a620 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 ite checks if th
1a630 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 is will mean tha
1a640 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 t there are now
1a650 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f no .** connectio
1a660 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 ns at all to the
1a670 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f database. If so
1a680 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 , it performs a
1a690 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f checkpoint .** o
1a6a0 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 peration before
1a6b0 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e closing the conn
1a6c0 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 ection. This opt
1a6d0 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 ion may be used
1a6e0 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 to.** override t
1a6f0 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 his behaviour. T
1a700 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
1a710 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 er passed to thi
1a720 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 s operation.** i
1a730 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 70 s an integer - p
1a740 6f 73 69 74 69 76 65 20 74 6f 20 64 69 73 61 62 ositive to disab
1a750 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f le checkpoints-o
1a760 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f n-close, or zero
1a770 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 (the.** default
1a780 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d ) to enable them
1a790 2c 20 61 6e 64 20 6e 65 67 61 74 69 76 65 20 74 , and negative t
1a7a0 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 o leave the sett
1a7b0 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a ing unchanged..*
1a7c0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 * The second par
1a7d0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e ameter is a poin
1a7e0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
1a7f0 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 r.** into which
1a800 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 is written 0 or
1a810 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 1 to indicate wh
1a820 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 ether checkpoint
1a830 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 s-on-close.** ha
1a840 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 ve been disabled
1a850 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65 - 0 if they are
1a860 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 not disabled, 1
1a870 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a if they are..**
1a880 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
1a890 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
1a8a0 4e 41 42 4c 45 5f 51 50 53 47 5d 5d 20 3c 64 74 NABLE_QPSG]] <dt
1a8b0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 >SQLITE_DBCONFIG
1a8c0 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 _ENABLE_QPSG</dt
1a8d0 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 >.** <dd>^(The S
1a8e0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
1a8f0 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f NABLE_QPSG optio
1a900 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 n activates or d
1a910 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 eactivates.** th
1a920 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 e [query planner
1a930 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72 61 stability guara
1a940 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57 ntee] (QPSG). W
1a950 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73 20 hen the QPSG is
1a960 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e active,.** a sin
1a970 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73 74 gle SQL query st
1a980 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 atement will alw
1a990 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65 ays use the same
1a9a0 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72 algorithm regar
1a9b0 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 dless.** of valu
1a9c0 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 es of [bound par
1a9d0 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 ameters].)^ The
1a9e0 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f QPSG disables so
1a9f0 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a me query optimiz
1aa00 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c ations.** that l
1aa10 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65 ook at the value
1aa20 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d s of bound param
1aa30 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e eters, which can
1aa40 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 make some queri
1aa50 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 es.** slower. B
1aa60 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73 20 ut the QPSG has
1aa70 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66 the advantage of
1aa80 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c more predictabl
1aa90 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74 e behavior. Wit
1aaa0 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63 h.** the QPSG ac
1aab0 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c tive, SQLite wil
1aac0 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 l always use the
1aad0 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e same query plan
1aae0 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73 in the field as
1aaf0 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75 72 .** was used dur
1ab00 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74 ing testing in t
1ab10 68 65 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66 he lab..** The f
1ab20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
1ab30 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 this setting is
1ab40 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 an integer whic
1ab50 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c h is 0 to disabl
1ab60 65 20 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c 20 e .** the QPSG,
1ab70 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 positive to enab
1ab80 6c 65 20 51 50 53 47 2c 20 6f 72 20 6e 65 67 61 le QPSG, or nega
1ab90 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 tive to leave th
1aba0 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 e setting.** unc
1abb0 68 61 6e 67 65 64 2e 20 54 68 65 20 73 65 63 6f hanged. The seco
1abc0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
1abd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
1abe0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 integer into whi
1abf0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e ch.** is written
1ac00 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 0 or 1 to indic
1ac10 61 74 65 20 77 68 65 74 68 65 72 20 74 68 65 20 ate whether the
1ac20 51 50 53 47 20 69 73 20 64 69 73 61 62 6c 65 64 QPSG is disabled
1ac30 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 or enabled.** f
1ac40 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 ollowing this ca
1ac50 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a ll..** </dd>.**.
1ac60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f ** [[SQLITE_DBCO
1ac70 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 NFIG_TRIGGER_EQP
1ac80 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 ]] <dt>SQLITE_DB
1ac90 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 CONFIG_TRIGGER_E
1aca0 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 QP</dt>.** <dd>
1acb0 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 By default, the
1acc0 6f 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49 output of EXPLAI
1acd0 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d N QUERY PLAN com
1ace0 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a mands does not .
1acf0 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75 ** include outpu
1ad00 74 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74 t for any operat
1ad10 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62 ions performed b
1ad20 79 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 y trigger progra
1ad30 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69 ms. This.** opti
1ad40 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 on is used to se
1ad50 74 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20 t or clear (the
1ad60 64 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20 default) a flag
1ad70 74 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69 that governs thi
1ad80 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54 s.** behavior. T
1ad90 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
1ada0 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 er passed to thi
1adb0 73 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 s operation is a
1adc0 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70 n integer -.** p
1add0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c ositive to enabl
1ade0 65 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69 e output for tri
1adf0 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f gger programs, o
1ae00 72 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c r zero to disabl
1ae10 65 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61 e it,.** or nega
1ae20 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 tive to leave th
1ae30 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e e setting unchan
1ae40 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f ged..** The seco
1ae50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
1ae60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
1ae70 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 integer into whi
1ae80 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a ch is written .*
1ae90 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 * 0 or 1 to indi
1aea0 63 61 74 65 20 77 68 65 74 68 65 72 20 6f 75 74 cate whether out
1aeb0 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73 put-for-triggers
1aec0 20 68 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c has been disabl
1aed0 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74 ed - 0 if .** it
1aee0 20 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 is not disabled
1aef0 2c 20 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a , 1 if it is. .
1af00 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ** </dd>.**.** [
1af10 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 [SQLITE_DBCONFIG
1af20 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 5d _RESET_DATABASE]
1af30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 ] <dt>SQLITE_DBC
1af40 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 ONFIG_RESET_DATA
1af50 42 41 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 BASE</dt>.** <dd
1af60 3e 20 53 65 74 20 74 68 65 20 53 51 4c 49 54 45 > Set the SQLITE
1af70 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f _DBCONFIG_RESET_
1af80 44 41 54 41 42 41 53 45 20 66 6c 61 67 20 61 6e DATABASE flag an
1af90 64 20 74 68 65 6e 20 72 75 6e 0a 2a 2a 20 5b 56 d then run.** [V
1afa0 41 43 55 55 4d 5d 20 69 6e 20 6f 72 64 65 72 20 ACUUM] in order
1afb0 74 6f 20 72 65 73 65 74 20 61 20 64 61 74 61 62 to reset a datab
1afc0 61 73 65 20 62 61 63 6b 20 74 6f 20 61 6e 20 65 ase back to an e
1afd0 6d 70 74 79 20 64 61 74 61 62 61 73 65 0a 2a 2a mpty database.**
1afe0 20 77 69 74 68 20 6e 6f 20 73 63 68 65 6d 61 20 with no schema
1aff0 61 6e 64 20 6e 6f 20 63 6f 6e 74 65 6e 74 2e 20 and no content.
1b000 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 The following pr
1b010 6f 63 65 73 73 20 77 6f 72 6b 73 20 65 76 65 6e ocess works even
1b020 20 66 6f 72 0a 2a 2a 20 61 20 62 61 64 6c 79 20 for.** a badly
1b030 63 6f 72 72 75 70 74 65 64 20 64 61 74 61 62 61 corrupted databa
1b040 73 65 20 66 69 6c 65 3a 0a 2a 2a 20 3c 6f 6c 3e se file:.** <ol>
1b050 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 74 68 65 20 .** <li> If the
1b060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1b070 69 6f 6e 20 69 73 20 6e 65 77 6c 79 20 6f 70 65 ion is newly ope
1b080 6e 65 64 2c 20 6d 61 6b 65 20 73 75 72 65 20 69 ned, make sure i
1b090 74 20 68 61 73 20 72 65 61 64 20 74 68 65 0a 2a t has read the.*
1b0a0 2a 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20 * database
1b0b0 73 63 68 65 6d 61 20 62 79 20 70 72 65 70 61 72 schema by prepar
1b0c0 69 6e 67 20 74 68 65 6e 20 64 69 73 63 61 72 64 ing then discard
1b0d0 69 6e 67 20 73 6f 6d 65 20 71 75 65 72 79 20 61 ing some query a
1b0e0 67 61 69 6e 73 74 20 74 68 65 0a 2a 2a 20 20 20 gainst the.**
1b0f0 20 20 20 64 61 74 61 62 61 73 65 2c 20 6f 72 20 database, or
1b100 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f calling sqlite3_
1b110 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 table_column_met
1b120 61 64 61 74 61 28 29 2c 20 69 67 6e 6f 72 69 6e adata(), ignorin
1b130 67 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 65 72 g any.** er
1b140 72 6f 72 73 2e 20 20 54 68 69 73 20 73 74 65 70 rors. This step
1b150 20 69 73 20 6f 6e 6c 79 20 6e 65 63 65 73 73 61 is only necessa
1b160 72 79 20 69 66 20 74 68 65 20 61 70 70 6c 69 63 ry if the applic
1b170 61 74 69 6f 6e 20 64 65 73 69 72 65 73 20 74 6f ation desires to
1b180 20 6b 65 65 70 0a 2a 2a 20 20 20 20 20 20 74 68 keep.** th
1b190 65 20 64 61 74 61 62 61 73 65 20 69 6e 20 57 41 e database in WA
1b1a0 4c 20 6d 6f 64 65 20 61 66 74 65 72 20 74 68 65 L mode after the
1b1b0 20 72 65 73 65 74 20 69 66 20 69 74 20 77 61 73 reset if it was
1b1c0 20 69 6e 20 57 41 4c 20 6d 6f 64 65 20 62 65 66 in WAL mode bef
1b1d0 6f 72 65 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 ore.** the
1b1e0 72 65 73 65 74 2e 20 20 0a 2a 2a 20 3c 6c 69 3e reset. .** <li>
1b1f0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
1b200 69 67 28 64 62 2c 20 53 51 4c 49 54 45 5f 44 42 ig(db, SQLITE_DB
1b210 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 CONFIG_RESET_DAT
1b220 41 42 41 53 45 2c 20 31 2c 20 30 29 3b 0a 2a 2a ABASE, 1, 0);.**
1b230 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 65 <li> [sqlite3_e
1b240 78 65 63 5d 28 64 62 2c 20 22 5b 56 41 43 55 55 xec](db, "[VACUU
1b250 4d 5d 22 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a M]", 0, 0, 0);.*
1b260 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64 * <li> sqlite3_d
1b270 62 5f 63 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c b_config(db, SQL
1b280 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 ITE_DBCONFIG_RES
1b290 45 54 5f 44 41 54 41 42 41 53 45 2c 20 30 2c 20 ET_DATABASE, 0,
1b2a0 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 20 0);.** </ol>.**
1b2b0 42 65 63 61 75 73 65 20 72 65 73 65 74 74 69 6e Because resettin
1b2c0 67 20 61 20 64 61 74 61 62 61 73 65 20 69 73 20 g a database is
1b2d0 64 65 73 74 72 75 63 74 69 76 65 20 61 6e 64 20 destructive and
1b2e0 69 72 72 65 76 65 72 73 69 62 6c 65 2c 20 74 68 irreversible, th
1b2f0 65 0a 2a 2a 20 70 72 6f 63 65 73 73 20 72 65 71 e.** process req
1b300 75 69 72 65 73 20 74 68 65 20 75 73 65 20 6f 66 uires the use of
1b310 20 74 68 69 73 20 6f 62 73 63 75 72 65 20 41 50 this obscure AP
1b320 49 20 61 6e 64 20 6d 75 6c 74 69 70 6c 65 20 73 I and multiple s
1b330 74 65 70 73 20 74 6f 20 68 65 6c 70 0a 2a 2a 20 teps to help.**
1b340 65 6e 73 75 72 65 20 74 68 61 74 20 69 74 20 64 ensure that it d
1b350 6f 65 73 20 6e 6f 74 20 68 61 70 70 65 6e 20 62 oes not happen b
1b360 79 20 61 63 63 69 64 65 6e 74 2e 0a 2a 2a 0a 2a y accident..**.*
1b370 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e * [[SQLITE_DBCON
1b380 46 49 47 5f 44 45 46 45 4e 53 49 56 45 5d 5d 20 FIG_DEFENSIVE]]
1b390 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e <dt>SQLITE_DBCON
1b3a0 46 49 47 5f 44 45 46 45 4e 53 49 56 45 3c 2f 64 FIG_DEFENSIVE</d
1b3b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 t>.** <dd>The SQ
1b3c0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 45 LITE_DBCONFIG_DE
1b3d0 46 45 4e 53 49 56 45 20 6f 70 74 69 6f 6e 20 61 FENSIVE option a
1b3e0 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 ctivates or deac
1b3f0 74 69 76 61 74 65 73 20 74 68 65 0a 2a 2a 20 22 tivates the.** "
1b400 64 65 66 65 6e 73 69 76 65 22 20 66 6c 61 67 20 defensive" flag
1b410 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 for a database c
1b420 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 57 68 65 6e onnection. When
1b430 20 74 68 65 20 64 65 66 65 6e 73 69 76 65 0a 2a the defensive.*
1b440 2a 20 66 6c 61 67 20 69 73 20 65 6e 61 62 6c 65 * flag is enable
1b450 64 2c 20 6c 61 6e 67 75 61 67 65 20 66 65 61 74 d, language feat
1b460 75 72 65 73 20 74 68 61 74 20 61 6c 6c 6f 77 20 ures that allow
1b470 6f 72 64 69 6e 61 72 79 20 53 51 4c 20 74 6f 20 ordinary SQL to
1b480 0a 2a 2a 20 64 65 6c 69 62 65 72 61 74 65 6c 79 .** deliberately
1b490 20 63 6f 72 72 75 70 74 20 74 68 65 20 64 61 74 corrupt the dat
1b4a0 61 62 61 73 65 20 66 69 6c 65 20 61 72 65 20 64 abase file are d
1b4b0 69 73 61 62 6c 65 64 2e 20 20 54 68 65 20 64 69 isabled. The di
1b4c0 73 61 62 6c 65 64 0a 2a 2a 20 66 65 61 74 75 72 sabled.** featur
1b4d0 65 73 20 69 6e 63 6c 75 64 65 20 62 75 74 20 61 es include but a
1b4e0 72 65 20 6e 6f 74 20 6c 69 6d 69 74 65 64 20 74 re not limited t
1b4f0 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a o the following:
1b500 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
1b510 20 54 68 65 20 5b 50 52 41 47 4d 41 20 77 72 69 The [PRAGMA wri
1b520 74 61 62 6c 65 5f 73 63 68 65 6d 61 3d 4f 4e 5d table_schema=ON]
1b530 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 3c statement..** <
1b540 6c 69 3e 20 57 72 69 74 65 73 20 74 6f 20 74 68 li> Writes to th
1b550 65 20 5b 73 71 6c 69 74 65 5f 64 62 70 61 67 65 e [sqlite_dbpage
1b560 5d 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e ] virtual table.
1b570 0a 2a 2a 20 3c 6c 69 3e 20 44 69 72 65 63 74 20 .** <li> Direct
1b580 77 72 69 74 65 73 20 74 6f 20 5b 73 68 61 64 6f writes to [shado
1b590 77 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 3c 2f w tables]..** </
1b5a0 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a ul>.** </dd>.**.
1b5b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f ** [[SQLITE_DBCO
1b5c0 4e 46 49 47 5f 57 52 49 54 41 42 4c 45 5f 53 43 NFIG_WRITABLE_SC
1b5d0 48 45 4d 41 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 HEMA]] <dt>SQLIT
1b5e0 45 5f 44 42 43 4f 4e 46 49 47 5f 57 52 49 54 41 E_DBCONFIG_WRITA
1b5f0 42 4c 45 5f 53 43 48 45 4d 41 3c 2f 64 74 3e 0a BLE_SCHEMA</dt>.
1b600 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 ** <dd>The SQLIT
1b610 45 5f 44 42 43 4f 4e 46 49 47 5f 57 52 49 54 41 E_DBCONFIG_WRITA
1b620 42 4c 45 5f 53 43 48 45 4d 41 20 6f 70 74 69 6f BLE_SCHEMA optio
1b630 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 n activates or d
1b640 65 61 63 74 69 76 61 74 65 73 20 74 68 65 0a 2a eactivates the.*
1b650 2a 20 22 77 72 69 74 61 62 6c 65 5f 73 63 68 65 * "writable_sche
1b660 6d 61 22 20 66 6c 61 67 2e 20 54 68 69 73 20 68 ma" flag. This h
1b670 61 73 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 as the same effe
1b680 63 74 20 61 6e 64 20 69 73 20 6c 6f 67 69 63 61 ct and is logica
1b690 6c 6c 79 20 65 71 75 69 76 61 6c 65 6e 74 0a 2a lly equivalent.*
1b6a0 2a 20 74 6f 20 73 65 74 74 69 6e 67 20 5b 50 52 * to setting [PR
1b6b0 41 47 4d 41 20 77 72 69 74 61 62 6c 65 5f 73 63 AGMA writable_sc
1b6c0 68 65 6d 61 3d 4f 4e 5d 20 6f 72 20 5b 50 52 41 hema=ON] or [PRA
1b6d0 47 4d 41 20 77 72 69 74 61 62 6c 65 5f 73 63 68 GMA writable_sch
1b6e0 65 6d 61 3d 4f 46 46 5d 2e 0a 2a 2a 20 54 68 65 ema=OFF]..** The
1b6f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
1b700 74 6f 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 to this setting
1b710 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 is an integer wh
1b720 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 ich is 0 to disa
1b730 62 6c 65 20 0a 2a 2a 20 74 68 65 20 77 72 69 74 ble .** the writ
1b740 61 62 6c 65 5f 73 63 68 65 6d 61 2c 20 70 6f 73 able_schema, pos
1b750 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 itive to enable
1b760 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61 2c writable_schema,
1b770 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 0a or negative to.
1b780 2a 2a 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 ** leave the set
1b790 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 20 ting unchanged.
1b7a0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
1b7b0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 eter is a pointe
1b7c0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 r to an.** integ
1b7d0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 er into which is
1b7e0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 written 0 or 1
1b7f0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 to indicate whet
1b800 68 65 72 20 74 68 65 20 77 72 69 74 61 62 6c 65 her the writable
1b810 5f 73 63 68 65 6d 61 0a 2a 2a 20 69 73 20 65 6e _schema.** is en
1b820 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 abled or disable
1b830 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 d following this
1b840 20 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a call..** </dd>.
1b850 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
1b860 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e ine SQLITE_DBCON
1b870 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20 FIG_MAINDBNAME
1b880 20 20 20 20 20 20 20 20 20 20 31 30 30 30 20 2f 1000 /
1b890 2a 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f * const char* */
1b8a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1b8b0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
1b8c0 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31 DE 1
1b8d0 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 001 /* void* int
1b8e0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
1b8f0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
1b900 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 ENABLE_FKEY
1b910 20 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 1002 /* in
1b920 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e t int* */.#defin
1b930 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
1b940 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 G_ENABLE_TRIGGER
1b950 20 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20 1003 /*
1b960 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 int int* */.#def
1b970 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e ine SQLITE_DBCON
1b980 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f FIG_ENABLE_FTS3_
1b990 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f TOKENIZER 1004 /
1b9a0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 * int int* */.#d
1b9b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 efine SQLITE_DBC
1b9c0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 ONFIG_ENABLE_LOA
1b9d0 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 D_EXTENSION 1005
1b9e0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a /* int int* */.
1b9f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1ba00 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f BCONFIG_NO_CKPT_
1ba10 4f 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20 31 30 ON_CLOSE 10
1ba20 30 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 06 /* int int* *
1ba30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1ba40 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
1ba50 5f 51 50 53 47 20 20 20 20 20 20 20 20 20 20 20 _QPSG
1ba60 31 30 30 37 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 1007 /* int int*
1ba70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1ba80 54 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49 47 TE_DBCONFIG_TRIG
1ba90 47 45 52 5f 45 51 50 20 20 20 20 20 20 20 20 20 GER_EQP
1baa0 20 20 31 30 30 38 20 2f 2a 20 69 6e 74 20 69 6e 1008 /* int in
1bab0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t* */.#define SQ
1bac0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 LITE_DBCONFIG_RE
1bad0 53 45 54 5f 44 41 54 41 42 41 53 45 20 20 20 20 SET_DATABASE
1bae0 20 20 20 20 31 30 30 39 20 2f 2a 20 69 6e 74 20 1009 /* int
1baf0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int* */.#define
1bb00 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
1bb10 44 45 46 45 4e 53 49 56 45 20 20 20 20 20 20 20 DEFENSIVE
1bb20 20 20 20 20 20 20 31 30 31 30 20 2f 2a 20 69 6e 1010 /* in
1bb30 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e t int* */.#defin
1bb40 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
1bb50 47 5f 57 52 49 54 41 42 4c 45 5f 53 43 48 45 4d G_WRITABLE_SCHEM
1bb60 41 20 20 20 20 20 20 20 31 30 31 31 20 2f 2a 20 A 1011 /*
1bb70 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 int int* */.#def
1bb80 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e ine SQLITE_DBCON
1bb90 46 49 47 5f 4d 41 58 20 20 20 20 20 20 20 20 20 FIG_MAX
1bba0 20 20 20 20 20 20 20 20 20 20 31 30 31 31 20 2f 1011 /
1bbb0 2a 20 4c 61 72 67 65 73 74 20 44 42 43 4f 4e 46 * Largest DBCONF
1bbc0 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 IG */../*.** CAP
1bbd0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 I3REF: Enable Or
1bbe0 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 Disable Extende
1bbf0 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a d Result Codes.*
1bc00 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
1bc10 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 3.**.** ^The sql
1bc20 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
1bc30 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 sult_codes() rou
1bc40 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 tine enables or
1bc50 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 disables the.**
1bc60 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
1bc70 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 codes] feature
1bc80 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 of SQLite. ^The
1bc90 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a extended result.
1bca0 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 ** codes are dis
1bcb0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
1bcc0 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 for historical
1bcd0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a compatibility..*
1bce0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 /.int sqlite3_ex
1bcf0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
1bd00 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e des(sqlite3*, in
1bd10 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a t onoff);../*.**
1bd20 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 CAPI3REF: Last
1bd30 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 Insert Rowid.**
1bd40 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
1bd50 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 **.** ^Each entr
1bd60 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 y in most SQLite
1bd70 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 tables (except
1bd80 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 for [WITHOUT ROW
1bd90 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 ID] tables).** h
1bda0 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 as a unique 64-b
1bdb0 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 it signed.** int
1bdc0 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 eger key called
1bdd0 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f the [ROWID | "ro
1bde0 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 wid"]. ^The rowi
1bdf0 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 d is always avai
1be00 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 lable.** as an u
1be10 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e ndeclared column
1be20 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 named ROWID, OI
1be30 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 D, or _ROWID_ as
1be40 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a long as those.*
1be50 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 * names are not
1be60 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 also used by exp
1be70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 licitly declared
1be80 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a columns. ^If.**
1be90 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 the table has a
1bea0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 column of type
1beb0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 [INTEGER PRIMARY
1bec0 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 KEY] then that
1bed0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f column.** is ano
1bee0 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 ther alias for t
1bef0 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 he rowid..**.**
1bf00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 ^The sqlite3_las
1bf10 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 t_insert_rowid(D
1bf20 29 20 69 6e 74 65 72 66 61 63 65 20 75 73 75 61 ) interface usua
1bf30 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 lly returns the
1bf40 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20 74 68 [rowid] of.** th
1bf50 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 e most recent su
1bf60 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
1bf70 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 ] into a rowid t
1bf80 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c able or [virtual
1bf90 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 table].** on da
1bfa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1bfb0 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73 20 69 6e n D. ^Inserts in
1bfc0 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 to [WITHOUT ROWI
1bfd0 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f D] tables are no
1bfe0 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e 20 5e t.** recorded. ^
1bff0 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c If no successful
1c000 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 [INSERT]s into
1c010 72 6f 77 69 64 20 74 61 62 6c 65 73 20 68 61 76 rowid tables hav
1c020 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 e ever occurred
1c030 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74 61 62 .** on the datab
1c040 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 ase connection D
1c050 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c , then sqlite3_l
1c060 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
1c070 28 44 29 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 (D) returns .**
1c080 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 zero..**.** As w
1c090 65 6c 6c 20 61 73 20 62 65 69 6e 67 20 73 65 74 ell as being set
1c0a0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 automatically a
1c0b0 73 20 72 6f 77 73 20 61 72 65 20 69 6e 73 65 72 s rows are inser
1c0c0 74 65 64 20 69 6e 74 6f 20 64 61 74 61 62 61 73 ted into databas
1c0d0 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74 68 65 e.** tables, the
1c0e0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
1c0f0 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e by this function
1c100 20 6d 61 79 20 62 65 20 73 65 74 20 65 78 70 6c may be set expl
1c110 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b 73 71 icitly by.** [sq
1c120 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 lite3_set_last_i
1c130 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a nsert_rowid()].*
1c140 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74 75 61 *.** Some virtua
1c150 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e l table implemen
1c160 74 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e 53 45 tations may INSE
1c170 52 54 20 72 6f 77 73 20 69 6e 74 6f 20 72 6f 77 RT rows into row
1c180 69 64 20 74 61 62 6c 65 73 20 61 73 0a 2a 2a 20 id tables as.**
1c190 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74 74 69 part of committi
1c1a0 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e ng a transaction
1c1b0 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73 68 20 (e.g. to flush
1c1c0 64 61 74 61 20 61 63 63 75 6d 75 6c 61 74 65 64 data accumulated
1c1d0 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 74 6f in memory.** to
1c1e0 20 64 69 73 6b 29 2e 20 49 6e 20 74 68 69 73 20 disk). In this
1c1f0 63 61 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 case subsequent
1c200 63 61 6c 6c 73 20 74 6f 20 74 68 69 73 20 66 75 calls to this fu
1c210 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 20 74 68 nction return th
1c220 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73 6f 63 e rowid.** assoc
1c230 69 61 74 65 64 20 77 69 74 68 20 74 68 65 73 65 iated with these
1c240 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45 52 54 internal INSERT
1c250 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77 68 69 operations, whi
1c260 63 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a 2a 20 ch leads to .**
1c270 75 6e 69 6e 74 75 69 74 69 76 65 20 72 65 73 75 unintuitive resu
1c280 6c 74 73 2e 20 56 69 72 74 75 61 6c 20 74 61 62 lts. Virtual tab
1c290 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
1c2a0 6e 73 20 74 68 61 74 20 64 6f 20 77 72 69 74 65 ns that do write
1c2b0 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74 61 62 to rowid.** tab
1c2c0 6c 65 73 20 69 6e 20 74 68 69 73 20 77 61 79 20 les in this way
1c2d0 63 61 6e 20 61 76 6f 69 64 20 74 68 69 73 20 70 can avoid this p
1c2e0 72 6f 62 6c 65 6d 20 62 79 20 72 65 73 74 6f 72 roblem by restor
1c2f0 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c ing the original
1c300 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c 75 65 .** rowid value
1c310 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
1c320 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f set_last_insert_
1c330 72 6f 77 69 64 28 29 5d 20 62 65 66 6f 72 65 20 rowid()] before
1c340 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20 63 6f returning .** co
1c350 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20 75 73 65 ntrol to the use
1c360 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e r..**.** ^(If an
1c370 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 [INSERT] occurs
1c380 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 within a trigge
1c390 72 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 r then this rout
1c3a0 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72 65 74 ine will .** ret
1c3b0 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 urn the [rowid]
1c3c0 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 20 of the inserted
1c3d0 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 row as long as t
1c3e0 68 65 20 74 72 69 67 67 65 72 20 69 73 20 0a 2a he trigger is .*
1c3f0 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63 65 20 * running. Once
1c400 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 the trigger prog
1c410 72 61 6d 20 65 6e 64 73 2c 20 74 68 65 20 76 61 ram ends, the va
1c420 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a lue returned .**
1c430 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 by this routine
1c440 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 reverts to what
1c450 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 it was before t
1c460 68 65 20 74 72 69 67 67 65 72 20 77 61 73 20 66 he trigger was f
1c470 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 ired.)^.**.** ^A
1c480 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 n [INSERT] that
1c490 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 fails due to a c
1c4a0 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
1c4b0 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 ion is not a.**
1c4c0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 successful [INSE
1c4d0 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 RT] and does not
1c4e0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 change the valu
1c4f0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 e returned by th
1c500 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 is.** routine.
1c510 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 ^Thus INSERT OR
1c520 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 FAIL, INSERT OR
1c530 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f IGNORE, INSERT O
1c540 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 R ROLLBACK,.** a
1c550 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f nd INSERT OR ABO
1c560 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 RT make no chang
1c570 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e es to the return
1c580 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a value of this.*
1c590 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 * routine when t
1c5a0 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 heir insertion f
1c5b0 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e ails. ^(When IN
1c5c0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a SERT OR REPLACE.
1c5d0 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 ** encounters a
1c5e0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
1c5f0 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f tion, it does no
1c600 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 t fail. The.**
1c610 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 INSERT continues
1c620 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 to completion a
1c630 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f fter deleting ro
1c640 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a ws that caused.*
1c650 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 * the constraint
1c660 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 problem so INSE
1c670 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 RT OR REPLACE wi
1c680 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 ll always change
1c690 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 .** the return v
1c6a0 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 alue of this int
1c6b0 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 erface.)^.**.**
1c6c0 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 ^For the purpose
1c6d0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e s of this routin
1c6e0 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 e, an [INSERT] i
1c6f0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a s considered to.
1c700 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c ** be successful
1c710 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 even if it is s
1c720 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c ubsequently roll
1c730 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 ed back..**.** T
1c740 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 his function is
1c750 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 accessible to SQ
1c760 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 L statements via
1c770 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e the.** [last_in
1c780 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c sert_rowid() SQL
1c790 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a function]..**.*
1c7a0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 * If a separate
1c7b0 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 thread performs
1c7c0 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f a new [INSERT] o
1c7d0 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 n the same.** da
1c7e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1c7f0 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c n while the [sql
1c800 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
1c810 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e _rowid()].** fun
1c820 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
1c830 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 and thus change
1c840 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 s the last inser
1c850 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 t [rowid],.** th
1c860 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 en the value ret
1c870 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
1c880 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
1c890 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 wid()] is.** unp
1c8a0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d redictable and m
1c8b0 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 ight not equal e
1c8c0 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 ither the old or
1c8d0 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 the new.** last
1c8e0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e insert [rowid].
1c8f0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 .*/.sqlite3_int6
1c900 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 4 sqlite3_last_i
1c910 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 nsert_rowid(sqli
1c920 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
1c930 50 49 33 52 45 46 3a 20 53 65 74 20 74 68 65 20 PI3REF: Set the
1c940 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 Last Insert Rowi
1c950 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45 54 48 d value..** METH
1c960 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
1c970 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 * The sqlite3_se
1c980 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f t_last_insert_ro
1c990 77 69 64 28 44 2c 20 52 29 20 6d 65 74 68 6f 64 wid(D, R) method
1c9a0 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 70 70 6c allows the appl
1c9b0 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 73 65 ication to.** se
1c9c0 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 t the value retu
1c9d0 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 rned by calling
1c9e0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
1c9f0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 74 6f 20 ert_rowid(D) to
1ca00 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20 69 6e R .** without in
1ca10 73 65 72 74 69 6e 67 20 61 20 72 6f 77 20 69 6e serting a row in
1ca20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e to the database.
1ca30 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 .*/.void sqlite3
1ca40 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 _set_last_insert
1ca50 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 2c _rowid(sqlite3*,
1ca60 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
1ca70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1ca80 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 Count The Numbe
1ca90 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 r Of Rows Modifi
1caa0 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ed.** METHOD: sq
1cab0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 lite3.**.** ^Thi
1cac0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
1cad0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
1cae0 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 rows modified,
1caf0 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 inserted or.** d
1cb00 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f eleted by the mo
1cb10 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 st recently comp
1cb20 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 leted INSERT, UP
1cb30 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a DATE or DELETE.*
1cb40 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 * statement on t
1cb50 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1cb60 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 ection specified
1cb70 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 by the only par
1cb80 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 ameter..** ^Exec
1cb90 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 uting any other
1cba0 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 type of SQL stat
1cbb0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d ement does not m
1cbc0 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a odify the value.
1cbd0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 ** returned by t
1cbe0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a his function..**
1cbf0 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 .** ^Only change
1cc00 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 s made directly
1cc10 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 by the INSERT, U
1cc20 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 PDATE or DELETE
1cc30 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a statement are.**
1cc40 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 considered - au
1cc50 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 xiliary changes
1cc60 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 caused by [CREAT
1cc70 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 E TRIGGER | trig
1cc80 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 gers], .** [fore
1cc90 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d ign key actions]
1cca0 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f or [REPLACE] co
1ccb0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 nstraint resolut
1ccc0 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e ion are not coun
1ccd0 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e ted..** .** Chan
1cce0 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 ges to a view th
1ccf0 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 at are intercept
1cd00 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 ed by .** [INSTE
1cd10 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 AD OF trigger |
1cd20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 INSTEAD OF trigg
1cd30 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 ers] are not cou
1cd40 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 nted. ^The value
1cd50 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 .** returned by
1cd60 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
1cd70 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 () immediately a
1cd80 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 fter an INSERT,
1cd90 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 UPDATE or .** DE
1cda0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 LETE statement r
1cdb0 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 un on a view is
1cdc0 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c always zero. Onl
1cdd0 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 y changes made t
1cde0 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 o real .** table
1cdf0 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a s are counted..*
1ce00 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 *.** Things are
1ce10 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 more complicated
1ce20 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f if the sqlite3_
1ce30 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 changes() functi
1ce40 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 on is.** execute
1ce50 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 d while a trigge
1ce60 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e r program is run
1ce70 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 ning. This may h
1ce80 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 appen if the.**
1ce90 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 program uses the
1cea0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 [changes() SQL
1ceb0 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 function], or if
1cec0 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c some other call
1ced0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e back.** function
1cee0 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 invokes sqlite3
1cef0 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 _changes() direc
1cf00 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 tly. Essentially
1cf10 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a :.** .** <ul>.**
1cf20 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 <li> ^(Before
1cf30 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 entering a trig
1cf40 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 ger program the
1cf50 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
1cf60 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 y.** sqli
1cf70 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 te3_changes() fu
1cf80 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e nction is saved.
1cf90 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67 After the trigg
1cfa0 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 er program .**
1cfb0 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 has finish
1cfc0 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c ed, the original
1cfd0 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 value is restor
1cfe0 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c ed.)^.** .** <
1cff0 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 li> ^(Within a t
1d000 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 rigger program e
1d010 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 ach INSERT, UPDA
1d020 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a TE and DELETE .*
1d030 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 * stateme
1d040 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 nt sets the valu
1d050 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 e returned by sq
1d060 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 lite3_changes()
1d070 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 .** upon
1d080 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f completion as no
1d090 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c rmal. Of course,
1d0a0 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c this value will
1d0b0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a not include .**
1d0c0 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e any chan
1d0d0 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 ges performed by
1d0e0 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 sub-triggers, a
1d0f0 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 s the sqlite3_ch
1d100 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 anges() .**
1d110 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 value will be
1d120 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f saved and resto
1d130 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73 red after each s
1d140 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 ub-trigger has r
1d150 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a un.)^.** </ul>.*
1d160 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e * .** ^This mean
1d170 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68 s that if the ch
1d180 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 anges() SQL func
1d190 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 tion (or similar
1d1a0 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 ) is used.** by
1d1b0 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 the first INSERT
1d1c0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 , UPDATE or DELE
1d1d0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 TE statement wit
1d1e0 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 hin a trigger, i
1d1f0 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 t .** returns th
1d200 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 e value as set w
1d210 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 hen the calling
1d220 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 statement began
1d230 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 executing..** ^I
1d240 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20 f it is used by
1d250 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 the second or su
1d260 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 bsequent such st
1d270 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 atement within a
1d280 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f trigger .** pro
1d290 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 gram, the value
1d2a0 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 returned reflect
1d2b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
1d2c0 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 rows modified by
1d2d0 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 the .** previou
1d2e0 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 s INSERT, UPDATE
1d2f0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 or DELETE state
1d300 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 ment within the
1d310 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a same trigger..**
1d320 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
1d330 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 e thread makes c
1d340 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 hanges on the sa
1d350 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
1d360 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 ection.** while
1d370 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 [sqlite3_changes
1d380 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
1d390 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
1d3a0 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 turned.** is unp
1d3b0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e redictable and n
1d3c0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a ot meaningful..*
1d3d0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 0a 2a *.** See also:.*
1d3e0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 74 * <ul>.** <li> t
1d3f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 he [sqlite3_tota
1d400 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 l_changes()] int
1d410 65 72 66 61 63 65 0a 2a 2a 20 3c 6c 69 3e 20 74 erface.** <li> t
1d420 68 65 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 he [count_change
1d430 73 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 s pragma].** <li
1d440 3e 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 > the [changes()
1d450 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a SQL function].*
1d460 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 64 61 74 61 * <li> the [data
1d470 5f 76 65 72 73 69 6f 6e 20 70 72 61 67 6d 61 5d _version pragma]
1d480 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 .** </ul>.*/.int
1d490 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
1d4a0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
1d4b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 ** CAPI3REF: Tot
1d4c0 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 al Number Of Row
1d4d0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 s Modified.** ME
1d4e0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
1d4f0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
1d500 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 on returns the t
1d510 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 otal number of r
1d520 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f ows inserted, mo
1d530 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c dified or.** del
1d540 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 eted by all [INS
1d550 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f ERT], [UPDATE] o
1d560 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 r [DELETE] state
1d570 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a ments completed.
1d580 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 ** since the dat
1d590 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1d5a0 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 was opened, inc
1d5b0 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 luding those exe
1d5c0 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 cuted as.** part
1d5d0 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 of trigger prog
1d5e0 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 rams. ^Executing
1d5f0 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 any other type
1d600 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 of SQL statement
1d610 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 .** does not aff
1d620 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 ect the value re
1d630 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
1d640 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
1d650 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 )..** .** ^Chang
1d660 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 es made as part
1d670 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 of [foreign key
1d680 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 actions] are inc
1d690 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 luded in the.**
1d6a0 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 count, but those
1d6b0 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 made as part of
1d6c0 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 REPLACE constra
1d6d0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 int resolution a
1d6e0 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e re.** not. ^Chan
1d6f0 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 ges to a view th
1d700 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 at are intercept
1d710 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 ed by INSTEAD OF
1d720 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 triggers .** ar
1d730 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a e not counted..*
1d740 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 *.** The [sqlite
1d750 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
1d760 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6f 6e D)] interface on
1d770 6c 79 20 72 65 70 6f 72 74 73 20 74 68 65 20 6e ly reports the n
1d780 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 72 6f 77 73 umber.** of rows
1d790 20 74 68 61 74 20 63 68 61 6e 67 65 64 20 64 75 that changed du
1d7a0 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 e to SQL stateme
1d7b0 6e 74 20 72 75 6e 20 61 67 61 69 6e 73 74 20 64 nt run against d
1d7c0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
1d7d0 63 74 69 6f 6e 20 44 2e 20 20 41 6e 79 20 63 68 ction D. Any ch
1d7e0 61 6e 67 65 73 20 62 79 20 6f 74 68 65 72 20 64 anges by other d
1d7f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1d800 6f 6e 73 20 61 72 65 20 69 67 6e 6f 72 65 64 2e ons are ignored.
1d810 0a 2a 2a 20 54 6f 20 64 65 74 65 63 74 20 63 68 .** To detect ch
1d820 61 6e 67 65 73 20 61 67 61 69 6e 73 74 20 61 20 anges against a
1d830 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 66 72 database file fr
1d840 6f 6d 20 6f 74 68 65 72 20 64 61 74 61 62 61 73 om other databas
1d850 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 e.** connections
1d860 20 75 73 65 20 74 68 65 20 5b 50 52 41 47 4d 41 use the [PRAGMA
1d870 20 64 61 74 61 5f 76 65 72 73 69 6f 6e 5d 20 63 data_version] c
1d880 6f 6d 6d 61 6e 64 20 6f 72 20 74 68 65 0a 2a 2a ommand or the.**
1d890 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 [SQLITE_FCNTL_D
1d8a0 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20 5b 66 69 ATA_VERSION] [fi
1d8b0 6c 65 20 63 6f 6e 74 72 6f 6c 5d 2e 0a 2a 2a 20 le control]..**
1d8c0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
1d8d0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 e thread makes c
1d8e0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 hanges on the sa
1d8f0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
1d900 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 ection.** while
1d910 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 [sqlite3_total_c
1d920 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e hanges()] is run
1d930 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 ning then the va
1d940 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lue.** returned
1d950 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 is unpredictable
1d960 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 and not meaning
1d970 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ful..**.** See a
1d980 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 lso:.** <ul>.**
1d990 3c 6c 69 3e 20 74 68 65 20 5b 73 71 6c 69 74 65 <li> the [sqlite
1d9a0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 3_changes()] int
1d9b0 65 72 66 61 63 65 0a 2a 2a 20 3c 6c 69 3e 20 74 erface.** <li> t
1d9c0 68 65 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 he [count_change
1d9d0 73 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 s pragma].** <li
1d9e0 3e 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 > the [changes()
1d9f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a SQL function].*
1da00 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 64 61 74 61 * <li> the [data
1da10 5f 76 65 72 73 69 6f 6e 20 70 72 61 67 6d 61 5d _version pragma]
1da20 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 53 51 .** <li> the [SQ
1da30 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f LITE_FCNTL_DATA_
1da40 56 45 52 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 VERSION] [file c
1da50 6f 6e 74 72 6f 6c 5d 0a 2a 2a 20 3c 2f 75 6c 3e ontrol].** </ul>
1da60 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
1da70 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 total_changes(sq
1da80 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
1da90 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 CAPI3REF: Interr
1daa0 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 upt A Long-Runni
1dab0 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 ng Query.** METH
1dac0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
1dad0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
1dae0 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 causes any pend
1daf0 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 ing database ope
1db00 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 ration to abort
1db10 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 and.** return at
1db20 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 its earliest op
1db30 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 portunity. This
1db40 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 routine is typic
1db50 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 ally.** called i
1db60 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 n response to a
1db70 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 user action such
1db80 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 as pressing "Ca
1db90 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c ncel".** or Ctrl
1dba0 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 -C where the use
1dbb0 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 r wants a long q
1dbc0 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 uery operation t
1dbd0 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 o halt.** immedi
1dbe0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 ately..**.** ^It
1dbf0 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c is safe to call
1dc00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 this routine fr
1dc10 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 om a thread diff
1dc20 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a erent from the.*
1dc30 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 * thread that is
1dc40 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 currently runni
1dc50 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ng the database
1dc60 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 operation. But
1dc70 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 it.** is not saf
1dc80 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 e to call this r
1dc90 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 outine with a [d
1dca0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1dcb0 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 on] that.** is c
1dcc0 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 losed or might c
1dcd0 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 lose before sqli
1dce0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
1dcf0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e returns..**.** ^
1dd00 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 If an SQL operat
1dd10 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 ion is very near
1dd20 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 ly finished at t
1dd30 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 he time when.**
1dd40 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
1dd50 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 t() is called, t
1dd60 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 hen it might not
1dd70 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 have an opportu
1dd80 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e nity.** to be in
1dd90 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 terrupted and mi
1dda0 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 ght continue to
1ddb0 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a completion..**.*
1ddc0 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 * ^An SQL operat
1ddd0 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 ion that is inte
1dde0 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 rrupted will ret
1ddf0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 urn [SQLITE_INTE
1de00 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 RRUPT]..** ^If t
1de10 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 he interrupted S
1de20 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 QL operation is
1de30 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 an INSERT, UPDAT
1de40 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 E, or DELETE.**
1de50 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 that is inside a
1de60 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 n explicit trans
1de70 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 action, then the
1de80 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 entire transact
1de90 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 ion.** will be r
1dea0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d olled back autom
1deb0 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 atically..**.**
1dec0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 ^The sqlite3_int
1ded0 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 errupt(D) call i
1dee0 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 s in effect unti
1def0 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 l all currently
1df00 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 running.** SQL s
1df10 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 tatements on [da
1df20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1df30 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 n] D complete.
1df40 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 ^Any new SQL sta
1df50 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 tements.** that
1df60 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 are started afte
1df70 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e r the sqlite3_in
1df80 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 terrupt() call a
1df90 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a nd before the .*
1dfa0 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d * running statem
1dfb0 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 ents reaches zer
1dfc0 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 o are interrupte
1dfd0 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 d as if they had
1dfe0 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 been.** running
1dff0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 prior to the sq
1e000 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
1e010 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 ) call. ^New SQ
1e020 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
1e030 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 that are started
1e040 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 after the runni
1e050 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 ng statement cou
1e060 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 nt reaches zero
1e070 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 are.** not effec
1e080 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 ted by the sqlit
1e090 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a e3_interrupt()..
1e0a0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 ** ^A call to sq
1e0b0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
1e0c0 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 D) that occurs w
1e0d0 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f hen there are no
1e0e0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 running.** SQL
1e0f0 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 statements is a
1e100 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f no-op and has no
1e110 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 effect on SQL s
1e120 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 tatements.** tha
1e130 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 t are started af
1e140 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f ter the sqlite3_
1e150 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c interrupt() call
1e160 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69 returns..*/.voi
1e170 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 d sqlite3_interr
1e180 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a upt(sqlite3*);..
1e190 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1e1a0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 Determine If An
1e1b0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 SQL Statement Is
1e1c0 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 Complete.**.**
1e1d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
1e1e0 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 re useful during
1e1f0 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e command-line in
1e200 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 put to determine
1e210 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 if the.** curre
1e220 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 ntly entered tex
1e230 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 t seems to form
1e240 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 a complete SQL s
1e250 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 tatement or.** i
1e260 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 f additional inp
1e270 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 ut is needed bef
1e280 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 ore sending the
1e290 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c text into.** SQL
1e2a0 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e ite for parsing.
1e2b0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ^These routine
1e2c0 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 s return 1 if th
1e2d0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a e input string.*
1e2e0 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 * appears to be
1e2f0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 a complete SQL s
1e300 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 tatement. ^A st
1e310 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 atement is judge
1e320 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c d to be.** compl
1e330 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 ete if it ends w
1e340 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 ith a semicolon
1e350 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 token and is not
1e360 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a a prefix of a.*
1e370 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 * well-formed CR
1e380 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 EATE TRIGGER sta
1e390 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f tement. ^Semico
1e3a0 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d lons that are em
1e3b0 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a bedded within.**
1e3c0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 string literals
1e3d0 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 or quoted ident
1e3e0 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 ifier names or c
1e3f0 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a omments are not.
1e400 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 ** independent t
1e410 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 okens (they are
1e420 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 part of the toke
1e430 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 n in which they
1e440 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 are.** embedded)
1e450 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 and thus do not
1e460 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 count as a stat
1e470 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 ement terminator
1e480 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a . ^Whitespace.*
1e490 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 * and comments t
1e4a0 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 hat follow the f
1e4b0 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 inal semicolon a
1e4c0 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a re ignored..**.*
1e4d0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
1e4e0 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 s return 0 if th
1e4f0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 e statement is i
1e500 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 ncomplete. ^If
1e510 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f a.** memory allo
1e520 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 cation fails, th
1e530 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 en SQLITE_NOMEM
1e540 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
1e550 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
1e560 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 es do not parse
1e570 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
1e580 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 ts thus.** will
1e590 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 not detect synta
1e5a0 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 ctically incorre
1e5b0 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ct SQL..**.** ^(
1e5c0 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f If SQLite has no
1e5d0 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a t been initializ
1e5e0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
1e5f0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 3_initialize()]
1e600 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 prior .** to inv
1e610 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f oking sqlite3_co
1e620 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 mplete16() then
1e630 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
1e640 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a ze() is invoked.
1e650 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ** automatically
1e660 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 by sqlite3_comp
1e670 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 lete16(). If th
1e680 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f at initializatio
1e690 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e n fails,.** then
1e6a0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
1e6b0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 e from sqlite3_c
1e6c0 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c omplete16() will
1e6d0 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 be non-zero.**
1e6e0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 regardless of wh
1e6f0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
1e700 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f input SQL is co
1e710 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 mplete.)^.**.**
1e720 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 The input to [sq
1e730 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 lite3_complete()
1e740 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f ] must be a zero
1e750 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 -terminated.** U
1e760 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a TF-8 string..**.
1e770 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 ** The input to
1e780 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
1e790 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 e16()] must be a
1e7a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1e7b0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e .** UTF-16 strin
1e7c0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 g in native byte
1e7d0 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 order..*/.int s
1e7e0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 qlite3_complete(
1e7f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 const char *sql)
1e800 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f ;.int sqlite3_co
1e810 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 mplete16(const v
1e820 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a oid *sql);../*.*
1e830 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 * CAPI3REF: Regi
1e840 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 ster A Callback
1e850 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 To Handle SQLITE
1e860 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 _BUSY Errors.**
1e870 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d KEYWORDS: {busy-
1e880 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b handler callback
1e890 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d } {busy handler}
1e8a0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
1e8b0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 te3.**.** ^The s
1e8c0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
1e8d0 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 ler(D,X,P) routi
1e8e0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 ne sets a callba
1e8f0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a ck function X.**
1e900 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 that might be i
1e910 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 nvoked with argu
1e920 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a ment P whenever.
1e930 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 ** an attempt is
1e940 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 made to access
1e950 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
1e960 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
1e970 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
1e980 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e nnection] D when
1e990 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a another thread.
1e9a0 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 ** or process ha
1e9b0 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b s the table lock
1e9c0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 ed..** The sqlit
1e9d0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
1e9e0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 ) interface is u
1e9f0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 sed to implement
1ea00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 .** [sqlite3_bus
1ea10 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 y_timeout()] and
1ea20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 [PRAGMA busy_ti
1ea30 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 meout]..**.** ^I
1ea40 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 f the busy callb
1ea50 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 ack is NULL, the
1ea60 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a n [SQLITE_BUSY].
1ea70 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 ** is returned i
1ea80 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 mmediately upon
1ea90 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 encountering the
1eaa0 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 lock. ^If the
1eab0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a busy callback.**
1eac0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 is not NULL, th
1ead0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
1eae0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 might be invoked
1eaf0 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 with two argume
1eb00 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
1eb10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
1eb20 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c o the busy handl
1eb30 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 er is a copy of
1eb40 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 the void* pointe
1eb50 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 r which.** is th
1eb60 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
1eb70 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 to sqlite3_busy
1eb80 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 _handler(). ^Th
1eb90 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
1eba0 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 t to.** the busy
1ebb0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 handler callbac
1ebc0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 k is the number
1ebd0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 of times that th
1ebe0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 e busy handler h
1ebf0 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b as.** been invok
1ec00 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f ed previously fo
1ec10 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 r the same locki
1ec20 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 ng event. ^If t
1ec30 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 he.** busy callb
1ec40 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 ack returns 0, t
1ec50 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 hen no additiona
1ec60 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d l attempts are m
1ec70 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 ade to.** access
1ec80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e the database an
1ec90 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 d [SQLITE_BUSY]
1eca0 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 is returned.** t
1ecb0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f o the applicatio
1ecc0 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 n..** ^If the ca
1ecd0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e llback returns n
1ece0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e on-zero, then an
1ecf0 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a other attempt.**
1ed00 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 is made to acce
1ed10 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ss the database
1ed20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 and the cycle re
1ed30 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 peats..**.** The
1ed40 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 presence of a b
1ed50 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 usy handler does
1ed60 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 not guarantee t
1ed70 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 hat it will be i
1ed80 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 nvoked.** when t
1ed90 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e here is lock con
1eda0 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c tention. ^If SQL
1edb0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 ite determines t
1edc0 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 hat invoking the
1edd0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 busy.** handler
1ede0 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e could result in
1edf0 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 a deadlock, it
1ee00 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e will go ahead an
1ee10 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 d return [SQLITE
1ee20 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 _BUSY].** to the
1ee30 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 application ins
1ee40 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 tead of invoking
1ee50 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 the .** busy ha
1ee60 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 ndler..** Consid
1ee70 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 er a scenario wh
1ee80 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 ere one process
1ee90 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 is holding a rea
1eea0 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 d lock that.** i
1eeb0 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 t is trying to p
1eec0 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 romote to a rese
1eed0 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a rved lock and.**
1eee0 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 a second proces
1eef0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 s is holding a r
1ef00 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 eserved lock tha
1ef10 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a t it is trying.*
1ef20 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 * to promote to
1ef30 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 an exclusive loc
1ef40 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 k. The first pr
1ef50 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f ocess cannot pro
1ef60 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 ceed.** because
1ef70 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 it is blocked by
1ef80 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 the second and
1ef90 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 the second proce
1efa0 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f ss cannot.** pro
1efb0 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 ceed because it
1efc0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 is blocked by th
1efd0 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 e first. If bot
1efe0 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 h processes.** i
1eff0 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 nvoke the busy h
1f000 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 andlers, neither
1f010 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 will make any p
1f020 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 rogress. Theref
1f030 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 ore,.** SQLite r
1f040 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 eturns [SQLITE_B
1f050 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 USY] for the fir
1f060 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 st process, hopi
1f070 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 ng that this.**
1f080 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 will induce the
1f090 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f first process to
1f0a0 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 release its rea
1f0b0 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 d lock and allow
1f0c0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 .** the second p
1f0d0 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 rocess to procee
1f0e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 d..**.** ^The de
1f0f0 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 fault busy callb
1f100 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a ack is NULL..**.
1f110 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f ** ^(There can o
1f120 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 nly be a single
1f130 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 busy handler def
1f140 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a ined for each.**
1f150 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1f160 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 ction]. Setting
1f170 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 a new busy hand
1f180 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a ler clears any.*
1f190 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 * previously set
1f1a0 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f handler.)^ ^No
1f1b0 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 te that calling
1f1c0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 [sqlite3_busy_ti
1f1d0 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 meout()].** or e
1f1e0 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d valuating [PRAGM
1f1f0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e A busy_timeout=N
1f200 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 ] will change th
1f210 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 e.** busy handle
1f220 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 r and thus clear
1f230 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 any previously
1f240 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 set busy handler
1f250 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 ..**.** The busy
1f260 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 callback should
1f270 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 not take any ac
1f280 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 tions which modi
1f290 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 fy the.** databa
1f2a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
1f2b0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 at invoked the b
1f2c0 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e usy handler. In
1f2d0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a other words,.**
1f2e0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
1f2f0 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 r is not reentra
1f300 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 nt. Any such ac
1f310 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 tions.** result
1f320 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 in undefined beh
1f330 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 avior..** .** A
1f340 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 busy handler mus
1f350 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 t not close the
1f360 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1f370 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 ion.** or [prepa
1f380 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
1f390 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
1f3a0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f busy handler..*/
1f3b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 .int sqlite3_bus
1f3c0 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 y_handler(sqlite
1f3d0 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 3*,int(*)(void*,
1f3e0 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a int),void*);../*
1f3f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 .** CAPI3REF: Se
1f400 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 t A Busy Timeout
1f410 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
1f420 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 te3.**.** ^This
1f430 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b routine sets a [
1f440 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
1f450 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 dler | busy hand
1f460 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 ler] that sleeps
1f470 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 .** for a specif
1f480 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 ied amount of ti
1f490 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 me when a table
1f4a0 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 is locked. ^The
1f4b0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c handler.** will
1f4c0 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 sleep multiple
1f4d0 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c times until at l
1f4e0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 east "ms" millis
1f4f0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
1f500 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d ng.** have accum
1f510 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 ulated. ^After
1f520 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 at least "ms" mi
1f530 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c lliseconds of sl
1f540 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 eeping,.** the h
1f550 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 andler returns 0
1f560 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 which causes [s
1f570 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 qlite3_step()] t
1f580 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c o return.** [SQL
1f590 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a ITE_BUSY]..**.**
1f5a0 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 ^Calling this r
1f5b0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 outine with an a
1f5c0 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 rgument less tha
1f5d0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 n or equal to ze
1f5e0 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 ro.** turns off
1f5f0 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 all busy handler
1f600 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 s..**.** ^(There
1f610 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 can only be a s
1f620 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c ingle busy handl
1f630 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 er for a particu
1f640 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 lar.** [database
1f650 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 connection] at
1f660 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 any given moment
1f670 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 . If another bu
1f680 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 sy handler.** wa
1f690 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e s defined (usin
1f6a0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f g [sqlite3_busy_
1f6b0 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f handler()]) prio
1f6c0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 r to calling.**
1f6d0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 this routine, th
1f6e0 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 at other busy ha
1f6f0 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 ndler is cleared
1f700 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c .)^.**.** See al
1f710 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 so: [PRAGMA bus
1f720 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e y_timeout].*/.in
1f730 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 t sqlite3_busy_t
1f740 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c imeout(sqlite3*,
1f750 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a int ms);../*.**
1f760 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 CAPI3REF: Conve
1f770 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 nience Routines
1f780 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 For Running Quer
1f790 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ies.** METHOD: s
1f7a0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 qlite3.**.** Thi
1f7b0 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e s is a legacy in
1f7c0 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 terface that is
1f7d0 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 preserved for ba
1f7e0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
1f7f0 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 ility..** Use of
1f800 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
1f810 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 is not recommend
1f820 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 ed..**.** Defini
1f830 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c tion: A <b>resul
1f840 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d t table</b> is m
1f850 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 emory data struc
1f860 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 ture created by
1f870 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
1f880 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 get_table()] int
1f890 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c erface. A resul
1f8a0 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 t table records
1f8b0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 the.** complete
1f8c0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 query results fr
1f8d0 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 om one or more q
1f8e0 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ueries..**.** Th
1f8f0 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 e table conceptu
1f900 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 ally has a numbe
1f910 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f r of rows and co
1f920 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 lumns. But.** t
1f930 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 hese numbers are
1f940 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 not part of the
1f950 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 result table it
1f960 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 self. These.**
1f970 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 numbers are obta
1f980 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e ined separately.
1f990 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e Let N be the n
1f9a0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a umber of rows.**
1f9b0 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 and M be the nu
1f9c0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e mber of columns.
1f9d0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 .**.** A result
1f9e0 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 table is an arra
1f9f0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
1fa00 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1fa10 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a UTF-8 strings..
1fa20 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b ** There are (N+
1fa30 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 1)*M elements in
1fa40 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 the array. The
1fa50 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 first M pointer
1fa60 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 s point.** to ze
1fa70 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 ro-terminated st
1fa80 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 rings that cont
1fa90 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 ain the names of
1faa0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a the columns..**
1fab0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 The remaining e
1fac0 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 ntries all point
1fad0 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 to query result
1fae0 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 s. NULL values
1faf0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c result.** in NUL
1fb00 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c L pointers. All
1fb10 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 other values ar
1fb20 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 e in their UTF-8
1fb30 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1fb40 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 .** string repre
1fb50 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 sentation as ret
1fb60 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
1fb70 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 3_column_text()]
1fb80 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 ..**.** A result
1fb90 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e table might con
1fba0 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d sist of one or m
1fbb0 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ore memory alloc
1fbc0 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 ations..** It is
1fbd0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 not safe to pas
1fbe0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 s a result table
1fbf0 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 directly to [sq
1fc00 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a lite3_free()]..*
1fc10 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 * A result table
1fc20 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c should be deall
1fc30 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 ocated using [sq
1fc40 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
1fc50 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 ()]..**.** ^(As
1fc60 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 an example of th
1fc70 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 e result table f
1fc80 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 ormat, suppose a
1fc90 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a query result.**
1fca0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a is as follows:.
1fcb0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
1fcc0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 e><pre>.**
1fcd0 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 Name |
1fce0 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d Age.** --
1fcf0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1fd00 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 -----.**
1fd10 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 Alice | 43
1fd20 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 .** Bob
1fd30 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 | 28.**
1fd40 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 Cindy
1fd50 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e | 21.** </pre>
1fd60 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
1fd70 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 .** There are tw
1fd80 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 o column (M==2)
1fd90 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 and three rows (
1fda0 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 N==3). Thus the
1fdb0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 .** result table
1fdc0 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 has 8 entries.
1fdd0 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 Suppose the res
1fde0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f ult table is sto
1fdf0 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 red.** in an arr
1fe00 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c ay names azResul
1fe10 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c t. Then azResul
1fe20 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e t holds this con
1fe30 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f tent:.**.** <blo
1fe40 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
1fe50 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1fe60 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 [0] = "Name"
1fe70 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
1fe80 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 sult[1] = "A
1fe90 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 ge";.** a
1fea0 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d zResult[2] =
1feb0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 "Alice";.**
1fec0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1fed0 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 ;3] = "43";.**
1fee0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
1fef0 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 91;4] = "Bob";.*
1ff00 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1ff10 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b t[5] = "28";
1ff20 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
1ff30 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 ult[6] = "Ci
1ff40 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 ndy";.**
1ff50 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 azResult[7]
1ff60 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 = "21";.** </pre
1ff70 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e ></blockquote>)^
1ff80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1ff90 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 te3_get_table()
1ffa0 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 function evaluat
1ffb0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a es one or more.*
1ffc0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 * semicolon-sepa
1ffd0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d rated SQL statem
1ffe0 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f ents in the zero
1fff0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
20000 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 8.** string of i
20010 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 ts 2nd parameter
20020 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 and returns a r
20030 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 esult table to t
20040 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 he.** pointer gi
20050 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 ven in its 3rd p
20060 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
20070 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 After the applic
20080 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 ation has finish
20090 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 ed with the resu
200a0 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f lt from sqlite3_
200b0 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 get_table(),.**
200c0 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 it must pass the
200d0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f result table po
200e0 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 inter to sqlite3
200f0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e _free_table() in
20100 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c order to.** rel
20110 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 ease the memory
20120 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 that was malloce
20130 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 d. Because of t
20140 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 he way the.** [s
20150 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
20160 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 happens within
20170 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
20180 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 e(), the calling
20190 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 .** function mus
201a0 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c t not try to cal
201b0 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 l [sqlite3_free(
201c0 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e )] directly. On
201d0 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 ly.** [sqlite3_f
201e0 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 ree_table()] is
201f0 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 able to release
20200 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 the memory prope
20210 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a rly and safely..
20220 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
20230 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 3_get_table() in
20240 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 terface is imple
20250 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 mented as a wrap
20260 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 per around.** [s
20270 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 qlite3_exec()].
20280 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
20290 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 _table() routine
202a0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 does not have a
202b0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 ccess.** to any
202c0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 internal data st
202d0 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 ructures of SQLi
202e0 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c te. It uses onl
202f0 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 y the public.**
20300 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 interface define
20310 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f d here. As a co
20320 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 nsequence, error
20330 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 s that occur in
20340 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c the.** wrapper l
20350 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 ayer outside of
20360 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 the internal [sq
20370 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 lite3_exec()] ca
20380 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 ll are not.** re
20390 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 flected in subse
203a0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b quent calls to [
203b0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
203c0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
203d0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 3_errmsg()]..*/.
203e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f int sqlite3_get_
203f0 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 table(. sqlite3
20400 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f *db, /
20410 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 * An open databa
20420 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 se */. const ch
20430 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a ar *zSql, /*
20440 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 SQL to be evalu
20450 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a ated */. char *
20460 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 **pazResult,
20470 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 /* Results of th
20480 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 e query */. int
20490 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 *pnRow,
204a0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 /* Number of
204b0 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 result rows writ
204c0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e ten here */. in
204d0 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 t *pnColumn,
204e0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 /* Number of
204f0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 result columns
20500 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
20510 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 char **pzErrms
20520 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 g /* Error
20530 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 msg written her
20540 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c e */.);.void sql
20550 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 ite3_free_table(
20560 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a char **result);.
20570 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
20580 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e Formatted Strin
20590 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 g Printing Funct
205a0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
205b0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f routines are wo
205c0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 rk-alikes of the
205d0 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 "printf()" fami
205e0 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a ly of functions.
205f0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e ** from the stan
20600 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a dard C library..
20610 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
20620 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 s understand mos
20630 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 t of the common
20640 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f formatting optio
20650 6e 73 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 ns from.** the s
20660 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 tandard library
20670 70 72 69 6e 74 66 28 29 20 0a 2a 2a 20 70 6c 75 printf() .** plu
20680 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 s some additiona
20690 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 l non-standard f
206a0 6f 72 6d 61 74 73 20 28 5b 25 71 5d 2c 20 5b 25 ormats ([%q], [%
206b0 51 5d 2c 20 5b 25 77 5d 2c 20 61 6e 64 20 5b 25 Q], [%w], and [%
206c0 7a 5d 29 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 z])..** See the
206d0 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 [built-in printf
206e0 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f ()] documentatio
206f0 6e 20 66 6f 72 20 64 65 74 61 69 6c 73 2e 0a 2a n for details..*
20700 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
20710 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 3_mprintf() and
20720 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
20730 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 () routines writ
20740 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c e their.** resul
20750 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f ts into memory o
20760 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
20770 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 lite3_malloc64()
20780 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 ]..** The string
20790 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
207a0 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 ese two routines
207b0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 should be.** re
207c0 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 leased by [sqlit
207d0 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f e3_free()]. ^Bo
207e0 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 th routines retu
207f0 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 rn a.** NULL poi
20800 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 nter if [sqlite3
20810 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 20 69 73 20 _malloc64()] is
20820 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
20830 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d te enough.** mem
20840 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 ory to hold the
20850 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 resulting string
20860 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 ..**.** ^(The sq
20870 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
20880 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 routine is simi
20890 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 lar to "snprintf
208a0 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 ()" from.** the
208b0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
208c0 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 ry. The result
208d0 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 is written into
208e0 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 the.** buffer su
208f0 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 pplied as the se
20900 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 cond parameter w
20910 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 hose size is giv
20920 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 en by.** the fir
20930 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f st parameter. No
20940 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 te that the orde
20950 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 r of the.** firs
20960 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 t two parameters
20970 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f is reversed fro
20980 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 m snprintf().)^
20990 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 This is an.** h
209a0 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 istorical accide
209b0 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 nt that cannot b
209c0 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 e fixed without
209d0 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b breaking.** back
209e0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
209f0 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 ity. ^(Note als
20a00 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 o that sqlite3_s
20a10 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 nprintf().** ret
20a20 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
20a30 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 o its buffer ins
20a40 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 tead of the numb
20a50 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 er of.** charact
20a60 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 ers actually wri
20a70 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 tten into the bu
20a80 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 ffer.)^ We admi
20a90 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 t that.** the nu
20aa0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 mber of characte
20ab0 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 rs written would
20ac0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 be a more usefu
20ad0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 l return.** valu
20ae0 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 e but we cannot
20af0 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 change the imple
20b00 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c mentation of sql
20b10 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a ite3_snprintf().
20b20 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 ** now without b
20b30 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 reaking compatib
20b40 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 ility..**.** ^As
20b50 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 long as the buf
20b60 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 fer size is grea
20b70 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 ter than zero, s
20b80 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
20b90 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 ).** guarantees
20ba0 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 that the buffer
20bb0 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 is always zero-t
20bc0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 erminated. ^The
20bd0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 first.** parame
20be0 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 ter "n" is the t
20bf0 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 otal size of the
20c00 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 buffer, includi
20c10 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 ng space for.**
20c20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 the zero termina
20c30 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e tor. So the lon
20c40 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 gest string that
20c50 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 can be complete
20c60 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 ly.** written wi
20c70 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 ll be n-1 charac
20c80 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ters..**.** ^The
20c90 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e sqlite3_vsnprin
20ca0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 tf() routine is
20cb0 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f a varargs versio
20cc0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 n of sqlite3_snp
20cd0 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 53 rintf()..**.** S
20ce0 65 65 20 61 6c 73 6f 3a 20 20 5b 62 75 69 6c 74 ee also: [built
20cf0 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d 2c 20 5b -in printf()], [
20d00 70 72 69 6e 74 66 28 29 20 53 51 4c 20 66 75 6e printf() SQL fun
20d10 63 74 69 6f 6e 5d 0a 2a 2f 0a 63 68 61 72 20 2a ction].*/.char *
20d20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
20d30 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 const char*,...)
20d40 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f ;.char *sqlite3_
20d50 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 vmprintf(const c
20d60 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a har*, va_list);.
20d70 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e char *sqlite3_sn
20d80 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a printf(int,char*
20d90 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e ,const char*, ..
20da0 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 .);.char *sqlite
20db0 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 3_vsnprintf(int,
20dc0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
20dd0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a *, va_list);../*
20de0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
20df0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 mory Allocation
20e00 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 Subsystem.**.**
20e10 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
20e20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 uses these three
20e30 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c routines for al
20e40 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 l of its own.**
20e50 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 internal memory
20e60 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
20e70 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 . "Core" in the
20e80 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 previous sentenc
20e90 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e e.** does not in
20ea0 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d clude operating-
20eb0 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 system specific
20ec0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
20ed0 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 on. The.** Wind
20ee0 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 ows VFS uses nat
20ef0 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 ive malloc() and
20f00 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 free() for some
20f10 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a operations..**.
20f20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
20f30 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 malloc() routine
20f40 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
20f50 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a er to a block.**
20f60 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 of memory at le
20f70 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c ast N bytes in l
20f80 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 ength, where N i
20f90 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e s the parameter.
20fa0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f .** ^If sqlite3_
20fb0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 malloc() is unab
20fc0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 le to obtain suf
20fd0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 ficient free.**
20fe0 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 memory, it retur
20ff0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
21000 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 r. ^If the para
21010 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 meter N to.** sq
21020 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 lite3_malloc() i
21030 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 s zero or negati
21040 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ve then sqlite3_
21050 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 malloc() returns
21060 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 .** a NULL point
21070 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
21080 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 qlite3_malloc64(
21090 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 N) routine works
210a0 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 just like.** sq
210b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 lite3_malloc(N)
210c0 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 except that N is
210d0 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d an unsigned 64-
210e0 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 bit integer inst
210f0 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e ead.** of a sign
21100 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 ed 32-bit intege
21110 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e r..**.** ^Callin
21120 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 g sqlite3_free()
21130 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 with a pointer
21140 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 previously retur
21150 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 ned.** by sqlite
21160 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 3_malloc() or sq
21170 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
21180 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 releases that me
21190 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 mory so.** that
211a0 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 it might be reus
211b0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 ed. ^The sqlite
211c0 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 3_free() routine
211d0 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 is.** a no-op i
211e0 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 f is called with
211f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
21200 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c Passing a NULL
21210 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 pointer.** to s
21220 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 qlite3_free() is
21230 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 harmless. Afte
21240 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d r being freed, m
21250 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 emory.** should
21260 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 neither be read
21270 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 nor written. Ev
21280 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 en reading previ
21290 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d ously freed.** m
212a0 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 emory might resu
212b0 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 lt in a segmenta
212c0 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 tion fault or ot
212d0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 her severe error
212e0 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 ..** Memory corr
212f0 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e uption, a segmen
21300 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 tation fault, or
21310 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 other severe er
21320 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 ror.** might res
21330 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 ult if sqlite3_f
21340 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 ree() is called
21350 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 with a non-NULL
21360 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 pointer that.**
21370 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 was not obtained
21380 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 from sqlite3_ma
21390 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 lloc() or sqlite
213a0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 3_realloc()..**.
213b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
213c0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 realloc(X,N) int
213d0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 erface attempts
213e0 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 to resize a.** p
213f0 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f rior memory allo
21400 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 cation X to be a
21410 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e t least N bytes.
21420 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 .** ^If the X pa
21430 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
21440 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a e3_realloc(X,N).
21450 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 ** is a NULL poi
21460 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 nter then its be
21470 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 havior is identi
21480 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a cal to calling.*
21490 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
214a0 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 (N)..** ^If the
214b0 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 N parameter to s
214c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 qlite3_realloc(X
214d0 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a ,N) is zero or.*
214e0 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 * negative then
214f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
21500 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 exactly the same
21510 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 as calling.** s
21520 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a qlite3_free(X)..
21530 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c ** ^sqlite3_real
21540 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 loc(X,N) returns
21550 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
21560 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
21570 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 n.** of at least
21580 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 N bytes in size
21590 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 or NULL if insu
215a0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 fficient memory
215b0 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a is available..**
215c0 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 ^If M is the si
215d0 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 ze of the prior
215e0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e allocation, then
215f0 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a min(N,M) bytes.
21600 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 ** of the prior
21610 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 allocation are c
21620 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 opied into the b
21630 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 eginning of buff
21640 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 er returned.** b
21650 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f y sqlite3_reallo
21660 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 c(X,N) and the p
21670 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
21680 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 is freed..** ^If
21690 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
216a0 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 (X,N) returns NU
216b0 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 LL and N is posi
216c0 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a tive, then the.*
216d0 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 * prior allocati
216e0 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e on is not freed.
216f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
21700 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c te3_realloc64(X,
21710 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f N) interfaces wo
21720 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a rks the same as.
21730 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c ** sqlite3_reall
21740 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 oc(X,N) except t
21750 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 hat N is a 64-bi
21760 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 t unsigned integ
21770 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 er instead.** of
21780 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 a 32-bit signed
21790 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 integer..**.**
217a0 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 ^If X is a memor
217b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 y allocation pre
217c0 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 viously obtained
217d0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 from sqlite3_ma
217e0 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 lloc(),.** sqlit
217f0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 e3_malloc64(), s
21800 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
21810 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 , or sqlite3_rea
21820 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a lloc64(), then.*
21830 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 * sqlite3_msize(
21840 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 X) returns the s
21850 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f ize of that memo
21860 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e ry allocation in
21870 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 bytes..** ^The
21880 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
21890 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 y sqlite3_msize(
218a0 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 X) might be larg
218b0 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 er than the numb
218c0 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 er.** of bytes r
218d0 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 equested when X
218e0 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 was allocated.
218f0 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 ^If X is a NULL
21900 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 pointer then.**
21910 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 sqlite3_msize(X)
21920 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 returns zero.
21930 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 If X points to s
21940 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 omething that is
21950 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 not.** the begi
21960 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 nning of memory
21970 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 allocation, or i
21980 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 f it points to a
21990 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c formerly.** val
219a0 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 id memory alloca
219b0 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f tion that has no
219c0 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 w been freed, th
219d0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a en the behavior.
219e0 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 ** of sqlite3_ms
219f0 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 ize(X) is undefi
21a00 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 ned and possibly
21a10 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 harmful..**.**
21a20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 ^The memory retu
21a30 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
21a40 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 malloc(), sqlite
21a50 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 3_realloc(),.**
21a60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 sqlite3_malloc64
21a70 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f (), and sqlite3_
21a80 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 realloc64().** i
21a90 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 s always aligned
21aa0 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 to at least an
21ab0 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 8 byte boundary,
21ac0 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 or to a.** 4 by
21ad0 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 te boundary if t
21ae0 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 he [SQLITE_4_BYT
21af0 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 E_ALIGNED_MALLOC
21b00 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a ] compile-time.*
21b10 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 * option is used
21b20 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 ..**.** In SQLit
21b30 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 e version 3.5.0
21b40 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 and 3.5.1, it wa
21b50 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 s possible to de
21b60 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 fine.** the SQLI
21b70 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 TE_OMIT_MEMORY_A
21b80 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 LLOCATION which
21b90 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 would cause the
21ba0 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c built-in.** impl
21bb0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
21bc0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 ese routines to
21bd0 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 be omitted. Tha
21be0 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 t capability.**
21bf0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f is no longer pro
21c00 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 vided. Only bui
21c10 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c lt-in memory all
21c20 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 ocators can be u
21c30 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 sed..**.** Prior
21c40 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 to SQLite versi
21c50 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 on 3.7.10, the W
21c60 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 indows OS interf
21c70 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 ace layer called
21c80 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d .** the system m
21c90 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 alloc() and free
21ca0 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e () directly when
21cb0 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 converting.** f
21cc0 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e ilenames between
21cd0 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 the UTF-8 encod
21ce0 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 ing used by SQLi
21cf0 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 te.** and whatev
21d00 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f er filename enco
21d10 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 ding is used by
21d20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 the particular W
21d30 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c indows.** instal
21d40 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 lation. Memory
21d50 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
21d60 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c s were detected,
21d70 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 but.** they wer
21d80 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 e reported back
21d90 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f as [SQLITE_CANTO
21da0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 PEN] or.** [SQLI
21db0 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 TE_IOERR] rather
21dc0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f than [SQLITE_NO
21dd0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 MEM]..**.** The
21de0 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 pointer argument
21df0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 s to [sqlite3_fr
21e00 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ee()] and [sqlit
21e10 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a e3_realloc()].**
21e20 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 must be either
21e30 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 NULL or else poi
21e40 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 nters obtained f
21e50 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 rom a prior.** i
21e60 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 nvocation of [sq
21e70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
21e80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c or [sqlite3_real
21e90 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 loc()] that have
21ea0 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e .** not yet been
21eb0 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a released..**.**
21ec0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
21ed0 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f must not read o
21ee0 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 r write any part
21ef0 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f of.** a block o
21f00 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 f memory after i
21f10 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 t has been relea
21f20 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 sed using.** [sq
21f30 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 lite3_free()] or
21f40 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
21f50 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 c()]..*/.void *s
21f60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e qlite3_malloc(in
21f70 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 t);.void *sqlite
21f80 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 3_malloc64(sqlit
21f90 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 e3_uint64);.void
21fa0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f *sqlite3_reallo
21fb0 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 c(void*, int);.v
21fc0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 oid *sqlite3_rea
21fd0 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 lloc64(void*, sq
21fe0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 lite3_uint64);.v
21ff0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 oid sqlite3_free
22000 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 (void*);.sqlite3
22010 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f _uint64 sqlite3_
22020 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f msize(void*);../
22030 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
22040 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 emory Allocator
22050 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a Statistics.**.**
22060 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 SQLite provides
22070 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 these two inter
22080 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 faces for report
22090 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 ing on the statu
220a0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c s.** of the [sql
220b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 ite3_malloc()],
220c0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
220d0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 , and [sqlite3_r
220e0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 ealloc()].** rou
220f0 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 tines, which for
22100 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d m the built-in m
22110 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
22120 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a subsystem..**.*
22130 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
22140 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 memory_used()] r
22150 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
22160 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
22170 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 es.** of memory
22180 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 currently outsta
22190 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 nding (malloced
221a0 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a but not freed)..
221b0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
221c0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
221d0 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 r()] routine ret
221e0 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d urns the maximum
221f0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 .** value of [sq
22200 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
22210 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 d()] since the h
22220 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a igh-water mark.*
22230 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 * was last reset
22240 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 . ^The values r
22250 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
22260 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
22270 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 )] and.** [sqlit
22280 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
22290 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 ter()] include a
222a0 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 ny overhead.** a
222b0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 dded by SQLite i
222c0 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 n its implementa
222d0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
222e0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 _malloc()],.** b
222f0 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 ut not overhead
22300 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 added by the any
22310 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 underlying syst
22320 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f em library.** ro
22330 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c utines that [sql
22340 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d ite3_malloc()] m
22350 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e ay call..**.** ^
22360 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d The memory high-
22370 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 water mark is re
22380 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 set to the curre
22390 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b nt value of.** [
223a0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
223b0 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e sed()] if and on
223c0 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 ly if the parame
223d0 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ter to.** [sqlit
223e0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
223f0 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 ter()] is true.
22400 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 ^The value retu
22410 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 rned.** by [sqli
22420 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
22430 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 ater(1)] is the
22440 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a high-water mark.
22450 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 ** prior to the
22460 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 reset..*/.sqlite
22470 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
22480 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 memory_used(void
22490 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 );.sqlite3_int64
224a0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f sqlite3_memory_
224b0 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 highwater(int re
224c0 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a setFlag);../*.**
224d0 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 CAPI3REF: Pseud
224e0 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 o-Random Number
224f0 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 Generator.**.**
22500 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 SQLite contains
22510 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 a high-quality p
22520 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d seudo-random num
22530 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 ber generator (P
22540 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 RNG) used to.**
22550 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 select random [R
22560 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 OWID | ROWIDs] w
22570 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 hen inserting ne
22580 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 w records into a
22590 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 table that.** a
225a0 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 lready uses the
225b0 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 largest possible
225c0 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 [ROWID]. The P
225d0 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 RNG is also used
225e0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c for.** the buil
225f0 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e d-in random() an
22600 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 d randomblob() S
22610 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 QL functions. T
22620 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c his interface al
22630 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 lows.** applicat
22640 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 ions to access t
22650 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 he same PRNG for
22660 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e other purposes.
22670 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 .**.** ^A call t
22680 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 o this routine s
22690 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 tores N bytes of
226a0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f randomness into
226b0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 buffer P..** ^T
226c0 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 he P parameter c
226d0 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 an be a NULL poi
226e0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 nter..**.** ^If
226f0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 this routine has
22700 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f not been previo
22710 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 usly called or i
22720 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a f the previous.*
22730 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 * call had N les
22740 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 s than one or a
22750 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 NULL pointer for
22760 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e P, then the PRN
22770 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 G is.** seeded u
22780 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 sing randomness
22790 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 obtained from th
227a0 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 e xRandomness me
227b0 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 thod of.** the d
227c0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f efault [sqlite3_
227d0 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 vfs] object..**
227e0 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 ^If the previous
227f0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f call to this ro
22800 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f utine had an N o
22810 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 f 1 or more and
22820 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 a.** non-NULL P
22830 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d then the pseudo-
22840 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 randomness is ge
22850 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 nerated.** inter
22860 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 nally and withou
22870 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 t recourse to th
22880 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 e [sqlite3_vfs]
22890 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d xRandomness.** m
228a0 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 ethod..*/.void s
228b0 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 qlite3_randomnes
228c0 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 s(int N, void *P
228d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
228e0 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 EF: Compile-Time
228f0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 Authorization C
22900 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 allbacks.** METH
22910 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b OD: sqlite3.** K
22920 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 EYWORDS: {author
22930 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a izer callback}.*
22940 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 *.** ^This routi
22950 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 ne registers an
22960 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
22970 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 ack with a parti
22980 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 cular.** [databa
22990 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 se connection],
229a0 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 supplied in the
229b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a first argument..
229c0 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a ** ^The authoriz
229d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
229e0 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 nvoked as SQL st
229f0 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 atements are bei
22a00 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 ng compiled.** b
22a10 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 y [sqlite3_prepa
22a20 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 re()] or its var
22a30 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 iants [sqlite3_p
22a40 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a repare_v2()],.**
22a50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
22a60 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 e_v3()], [sqlite
22a70 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 3_prepare16()],
22a80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
22a90 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 16_v2()],.** and
22aa0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
22ab0 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 e16_v3()]. ^At
22ac0 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 various.** point
22ad0 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d s during the com
22ae0 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 pilation process
22af0 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 , as logic is be
22b00 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 ing created.** t
22b10 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 o perform variou
22b20 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 s actions, the a
22b30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
22b40 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f ck is invoked to
22b50 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 .** see if those
22b60 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c actions are all
22b70 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 owed. ^The auth
22b80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
22b90 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e should.** return
22ba0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 [SQLITE_OK] to
22bb0 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e allow the action
22bc0 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 , [SQLITE_IGNORE
22bd0 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 ] to disallow th
22be0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 e.** specific ac
22bf0 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 tion but allow t
22c00 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
22c10 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 to continue to
22c20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 be.** compiled,
22c30 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d or [SQLITE_DENY]
22c40 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e to cause the en
22c50 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 tire SQL stateme
22c60 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 nt to be.** reje
22c70 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 cted with an err
22c80 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 or. ^If the aut
22c90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
22ca0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 returns.** any
22cb0 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e value other than
22cc0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
22cd0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f , [SQLITE_OK], o
22ce0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a r [SQLITE_DENY].
22cf0 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c ** then the [sql
22d00 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
22d10 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 )] or equivalent
22d20 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 call that trigg
22d30 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 ered.** the auth
22d40 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c orizer will fail
22d50 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d with an error m
22d60 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 essage..**.** Wh
22d70 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
22d80 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
22d90 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 OK], that means
22da0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a the operation.**
22db0 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b requested is ok
22dc0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c . ^When the cal
22dd0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 lback returns [S
22de0 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 QLITE_DENY], the
22df0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
22e00 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 pare_v2()] or eq
22e10 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 uivalent call th
22e20 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 at triggered the
22e30 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 .** authorizer w
22e40 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e ill fail with an
22e50 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 error message e
22e60 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a xplaining that.*
22e70 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 * access is deni
22e80 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ed. .**.** ^The
22e90 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
22ea0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 to the authorize
22eb0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 r callback is a
22ec0 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 copy of the thir
22ed0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 d.** parameter t
22ee0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 o the sqlite3_se
22ef0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 t_authorizer() i
22f00 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 nterface. ^The s
22f10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a econd parameter.
22f20 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 ** to the callba
22f30 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ck is an integer
22f40 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 [SQLITE_COPY |
22f50 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 action code] tha
22f60 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 t specifies.** t
22f70 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 he particular ac
22f80 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f tion to be autho
22f90 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 rized. ^The thir
22fa0 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 d through sixth
22fb0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f parameters.** to
22fc0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 the callback ar
22fd0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f e either NULL po
22fe0 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 inters or zero-t
22ff0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 erminated string
23000 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 s.** that contai
23010 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 n additional det
23020 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 ails about the a
23030 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 ction to be auth
23040 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 orized..** Appli
23050 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 cations must alw
23060 61 79 73 20 62 65 20 70 72 65 70 61 72 65 64 20 ays be prepared
23070 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e to encounter a N
23080 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 ULL pointer in a
23090 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 ny.** of the thi
230a0 72 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 rd through the s
230b0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 ixth parameters
230c0 6f 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 of the authoriza
230d0 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a tion callback..*
230e0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 *.** ^If the act
230f0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c ion code is [SQL
23100 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 ITE_READ].** and
23110 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
23120 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 turns [SQLITE_IG
23130 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a NORE] then the.*
23140 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
23150 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 ement] statement
23160 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 is constructed
23170 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a to substitute.**
23180 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e a NULL value in
23190 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 place of the ta
231a0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 ble column that
231b0 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 would have.** be
231c0 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 en read if [SQLI
231d0 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 TE_OK] had been
231e0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b returned. The [
231f0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a SQLITE_IGNORE].*
23200 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 * return can be
23210 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 used to deny an
23220 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 untrusted user a
23230 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 ccess to individ
23240 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f ual.** columns o
23250 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 f a table..** ^W
23260 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72 hen a table is r
23270 65 66 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b eferenced by a [
23280 53 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 SELECT] but no c
23290 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 olumn values are
232a0 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66 72 .** extracted fr
232b0 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28 66 om that table (f
232c0 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 or example in a
232d0 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 query like.** "S
232e0 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 ELECT count(*) F
232f0 52 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74 ROM tab") then t
23300 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d he [SQLITE_READ]
23310 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
23320 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b back.** is invok
23330 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 ed once for that
23340 20 74 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f table with a co
23350 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 lumn name that i
23360 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e s an empty strin
23370 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 g..** ^If the ac
23380 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 tion code is [SQ
23390 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 LITE_DELETE] and
233a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
233b0 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 turns.** [SQLITE
233c0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 _IGNORE] then th
233d0 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 e [DELETE] opera
233e0 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 tion proceeds bu
233f0 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 t the.** [trunca
23400 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d te optimization]
23410 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 is disabled and
23420 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 all rows are de
23430 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c leted individual
23440 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 ly..**.** An aut
23450 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 horizer is used
23460 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 when [sqlite3_pr
23470 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e epare | preparin
23480 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d g].** SQL statem
23490 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 ents from an unt
234a0 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 rusted source, t
234b0 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 o ensure that th
234c0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
234d0 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 .** do not try t
234e0 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 o access data th
234f0 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 ey are not allow
23500 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 ed to see, or th
23510 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a at they do not.*
23520 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 * try to execute
23530 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 malicious state
23540 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 ments that damag
23550 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 e the database.
23560 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c For.** example,
23570 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
23580 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 may allow a user
23590 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 to enter arbitr
235a0 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 ary.** SQL queri
235b0 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f es for evaluatio
235c0 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e n by a database.
235d0 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 But the applic
235e0 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f ation does.** no
235f0 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 t want the user
23600 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 to be able to ma
23610 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 ke arbitrary cha
23620 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 nges to the.** d
23630 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 atabase. An aut
23640 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 horizer could th
23650 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 en be put in pla
23660 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 ce while the.**
23670 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c user-entered SQL
23680 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 is being [sqlit
23690 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 e3_prepare | pre
236a0 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 pared] that.** d
236b0 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 isallows everyth
236c0 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 ing except [SELE
236d0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a CT] statements..
236e0 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f **.** Applicatio
236f0 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 ns that need to
23700 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d process SQL from
23710 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 untrusted sourc
23720 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f es.** might also
23730 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 consider loweri
23740 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 ng resource limi
23750 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ts using [sqlite
23760 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 3_limit()].** an
23770 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 d limiting datab
23780 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 ase size using t
23790 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 he [max_page_cou
237a0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 nt] [PRAGMA].**
237b0 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 in addition to u
237c0 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a sing an authoriz
237d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 er..**.** ^(Only
237e0 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 a single author
237f0 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 izer can be in p
23800 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 lace on a databa
23810 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
23820 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 at a time. Eac
23830 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 h call to sqlite
23840 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
23850 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a overrides the.*
23860 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e * previous call.
23870 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 )^ ^Disable the
23880 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 authorizer by i
23890 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c nstalling a NULL
238a0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 callback..** Th
238b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 e authorizer is
238c0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
238d0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 ult..**.** The a
238e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
238f0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 ck must not do a
23900 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c nything that wil
23910 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 l modify.** the
23920 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
23930 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 ion that invoked
23940 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
23950 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 callback..** Not
23960 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f e that [sqlite3_
23970 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
23980 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 d [sqlite3_step(
23990 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 )] both modify t
239a0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 heir.** database
239b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 connections for
239c0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 the meaning of
239d0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 "modify" in this
239e0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a paragraph..**.*
239f0 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 * ^When [sqlite3
23a00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 _prepare_v2()] i
23a10 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 s used to prepar
23a20 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 e a statement, t
23a30 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 he.** statement
23a40 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 might be re-prep
23a50 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c ared during [sql
23a60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 ite3_step()] due
23a70 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 to a .** schema
23a80 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c change. Hence,
23a90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
23aa0 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 should ensure t
23ab0 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 hat the.** corre
23ac0 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 ct authorizer ca
23ad0 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 llback remains i
23ae0 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 n place during t
23af0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 he [sqlite3_step
23b00 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 ()]..**.** ^Note
23b10 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 that the author
23b20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
23b30 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 invoked only du
23b40 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ring.** [sqlite3
23b50 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 _prepare()] or i
23b60 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 ts variants. Au
23b70 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e thorization is n
23b80 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 ot.** performed
23b90 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 during statement
23ba0 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b evaluation in [
23bb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c sqlite3_step()],
23bc0 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 unless.** as st
23bd0 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 ated in the prev
23be0 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 ious paragraph,
23bf0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
23c00 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 nvokes.** sqlite
23c10 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 3_prepare_v2() t
23c20 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 o reprepare a st
23c30 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 atement after a
23c40 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a schema change..*
23c50 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 /.int sqlite3_se
23c60 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 t_authorizer(.
23c70 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 sqlite3*,. int
23c80 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 (*xAuth)(void*,i
23c90 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 nt,const char*,c
23ca0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 onst char*,const
23cb0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 char*,const cha
23cc0 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 r*),. void *pUs
23cd0 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a erData.);../*.**
23ce0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f CAPI3REF: Autho
23cf0 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 rizer Return Cod
23d00 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 es.**.** The [sq
23d10 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
23d20 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 izer | authorize
23d30 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 r callback funct
23d40 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 ion] must.** ret
23d50 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 urn either [SQLI
23d60 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 TE_OK] or one of
23d70 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 these two const
23d80 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a ants in order.**
23d90 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 to signal SQLit
23da0 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 e whether or not
23db0 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 the action is p
23dc0 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 ermitted. See t
23dd0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 he.** [sqlite3_s
23de0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 et_authorizer |
23df0 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d authorizer docum
23e00 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 entation] for ad
23e10 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f ditional.** info
23e20 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e rmation..**.** N
23e30 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f ote that SQLITE_
23e40 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 IGNORE is also u
23e50 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 sed as a [confli
23e60 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f ct resolution mo
23e70 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 de].** returned
23e80 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 from the [sqlite
23e90 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 3_vtab_on_confli
23ea0 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e ct()] interface.
23eb0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
23ec0 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a TE_DENY 1 /*
23ed0 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 Abort the SQL s
23ee0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e tatement with an
23ef0 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e error */.#defin
23f00 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 e SQLITE_IGNORE
23f10 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 2 /* Don't all
23f20 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 ow access, but d
23f30 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e on't generate an
23f40 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a error */../*.**
23f50 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f CAPI3REF: Autho
23f60 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 rizer Action Cod
23f70 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 es.**.** The [sq
23f80 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
23f90 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 izer()] interfac
23fa0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 e registers a ca
23fb0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a llback function.
23fc0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b ** that is invok
23fd0 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 ed to authorize
23fe0 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 certain SQL stat
23ff0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 ement actions.
24000 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 The.** second pa
24010 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 rameter to the c
24020 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e allback is an in
24030 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 teger code that
24040 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 specifies.** wha
24050 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e t action is bein
24060 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 g authorized. T
24070 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 hese are the int
24080 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 eger action code
24090 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 s that.** the au
240a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
240b0 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e k may be passed.
240c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 .**.** These act
240d0 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 ion code values
240e0 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e signify what kin
240f0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 d of operation i
24100 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f s to be.** autho
24110 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 rized. The 3rd
24120 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 and 4th paramete
24130 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 rs to the author
24140 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 ization.** callb
24150 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c ack function wil
24160 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 l be parameters
24170 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e or NULL dependin
24180 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 g on which of th
24190 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 ese.** codes is
241a0 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f used as the seco
241b0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e nd parameter. ^
241c0 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 (The 5th paramet
241d0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 er to the.** aut
241e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
241f0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
24200 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d the database ("m
24210 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a ain", "temp",.**
24220 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 etc.) if applic
24230 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 able.)^ ^The 6t
24240 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
24250 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
24260 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 llback.** is the
24270 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e name of the inn
24280 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 er-most trigger
24290 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 or view that is
242a0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a responsible for.
242b0 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 ** the access at
242c0 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 tempt or NULL if
242d0 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 this access att
242e0 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 empt is directly
242f0 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 from.** top-lev
24300 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a el SQL code..*/.
24310 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /***************
24320 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
24330 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 ************ 3rd
24340 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 ************ 4t
24350 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 h ***********/.#
24360 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
24370 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 EATE_INDEX
24380 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 1 /* Index
24390 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
243a0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
243b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
243c0 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 ATE_TABLE
243d0 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 2 /* Table
243e0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
243f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
24400 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
24410 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 TE_TEMP_INDEX
24420 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 3 /* Index N
24430 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
24440 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
24450 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
24460 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 E_TEMP_TABLE
24470 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 4 /* Table Na
24480 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
24490 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
244a0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
244b0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 _TEMP_TRIGGER
244c0 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 5 /* Trigger N
244d0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
244e0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
244f0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
24500 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 TEMP_VIEW 6
24510 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
24520 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
24530 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
24540 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
24550 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 RIGGER 7
24560 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
24570 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
24580 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
24590 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 SQLITE_CREATE_VI
245a0 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 EW 8
245b0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
245c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
245d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
245e0 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 QLITE_DELETE
245f0 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 9
24600 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
24610 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
24620 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
24630 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 LITE_DROP_INDEX
24640 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 10 /
24650 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
24660 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
24670 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
24680 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 ITE_DROP_TABLE
24690 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 11 /*
246a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
246b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
246c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
246d0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 TE_DROP_TEMP_IND
246e0 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 EX 12 /*
246f0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
24700 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
24710 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
24720 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c E_DROP_TEMP_TABL
24730 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 E 13 /* T
24740 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
24750 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
24760 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
24770 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 _DROP_TEMP_TRIGG
24780 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 ER 14 /* Tr
24790 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger Name Ta
247a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
247b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
247c0 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 DROP_TEMP_VIEW
247d0 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 15 /* Vie
247e0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w Name NUL
247f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
24800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
24810 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 ROP_TRIGGER
24820 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 16 /* Trig
24830 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
24840 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
24850 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
24860 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 OP_VIEW
24870 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 17 /* View
24880 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
24890 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
248a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 efine SQLITE_INS
248b0 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 ERT
248c0 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 18 /* Table
248d0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
248e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
248f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 fine SQLITE_PRAG
24900 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 MA
24910 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 19 /* Pragma
24920 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 Name 1st arg
24930 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 or NULL */.#def
24940 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 ine SQLITE_READ
24950 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
24960 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 20 /* Table Na
24970 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e me Column N
24980 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
24990 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 ne SQLITE_SELECT
249a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
249b0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 1 /* NULL
249c0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
249d0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
249e0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 e SQLITE_TRANSAC
249f0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 TION 22
24a00 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 /* Operation
24a10 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
24a20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
24a30 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 SQLITE_UPDATE
24a40 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 23
24a50 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
24a60 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 Column Name
24a70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
24a80 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 SQLITE_ATTACH
24a90 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 24
24aa0 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 /* Filename
24ab0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
24ac0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
24ad0 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 QLITE_DETACH
24ae0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 25
24af0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 /* Database Name
24b00 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
24b10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
24b20 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 LITE_ALTER_TABLE
24b30 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 26 /
24b40 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 * Database Name
24b50 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
24b60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
24b70 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 ITE_REINDEX
24b80 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 27 /*
24b90 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
24ba0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
24bb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
24bc0 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 TE_ANALYZE
24bd0 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 28 /*
24be0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
24bf0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
24c00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
24c10 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 E_CREATE_VTABLE
24c20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 29 /* T
24c30 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d able Name M
24c40 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a odule Name *
24c50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
24c60 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 _DROP_VTABLE
24c70 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 30 /* Ta
24c80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f ble Name Mo
24c90 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f dule Name */
24ca0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
24cb0 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 FUNCTION
24cc0 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 31 /* NUL
24cd0 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e L Fun
24ce0 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a ction Name */.
24cf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
24d00 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 AVEPOINT
24d10 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 32 /* Oper
24d20 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 ation Save
24d30 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 point Name */.#
24d40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
24d50 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 PY
24d60 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 0 /* No lo
24d70 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 nger used */.#de
24d80 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 fine SQLITE_RECU
24d90 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 RSIVE
24da0 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 33 /* NULL
24db0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 NULL
24dc0 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a */../*.
24dd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 ** CAPI3REF: Tra
24de0 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 cing And Profili
24df0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 ng Functions.**
24e00 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
24e10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
24e20 69 6e 65 73 20 61 72 65 20 64 65 70 72 65 63 61 ines are depreca
24e30 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 ted. Use the [sq
24e40 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 lite3_trace_v2()
24e50 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 ] interface.** i
24e60 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f nstead of the ro
24e70 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 utines described
24e80 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 here..**.** The
24e90 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 se routines regi
24ea0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 ster callback fu
24eb0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e nctions that can
24ec0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 be used for.**
24ed0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 tracing and prof
24ee0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 iling the execut
24ef0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 ion of SQL state
24f00 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ments..**.** ^Th
24f10 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
24f20 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
24f30 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 y sqlite3_trace(
24f40 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a ) is invoked at.
24f50 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 ** various times
24f60 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 when an SQL sta
24f70 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 tement is being
24f80 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f run by [sqlite3_
24f90 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 step()]..** ^The
24fa0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 sqlite3_trace()
24fb0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
24fc0 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d oked with a UTF-
24fd0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 8 rendering of t
24fe0 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d he.** SQL statem
24ff0 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 ent text as the
25000 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 statement first
25010 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 begins executing
25020 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 ..** ^(Additiona
25030 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 l sqlite3_trace(
25040 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 ) callbacks migh
25050 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 t occur.** as ea
25060 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 ch triggered sub
25070 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 program is enter
25080 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 ed. The callbac
25090 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a ks for triggers.
250a0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 ** contain a UTF
250b0 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 -8 SQL comment t
250c0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 hat identifies t
250d0 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a he trigger.)^.**
250e0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
250f0 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 TRACE_SIZE_LIMIT
25100 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
25110 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 ption can be use
25120 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 d to limit.** th
25130 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 e length of [bou
25140 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 nd parameter] ex
25150 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f pansion in the o
25160 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 utput of sqlite3
25170 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 _trace()..**.**
25180 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 ^The callback fu
25190 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
251a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f d by sqlite3_pro
251b0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 file() is invoke
251c0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c d.** as each SQL
251d0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 statement finis
251e0 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 hes. ^The profi
251f0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 le callback cont
25200 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 ains.** the orig
25210 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 inal statement t
25220 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d ext and an estim
25230 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 ate of wall-cloc
25240 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 k time.** of how
25250 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 long that state
25260 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e ment took to run
25270 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 . ^The profile
25280 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 callback.** time
25290 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 is in units of
252a0 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 nanoseconds, how
252b0 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 ever the current
252c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a implementation.
252d0 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 ** is only capab
252e0 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e le of millisecon
252f0 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 d resolution so
25300 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 the six least si
25310 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 gnificant.** dig
25320 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 its in the time
25330 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e are meaningless.
25340 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e Future version
25350 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d s of SQLite.** m
25360 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 ight provide gre
25370 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 ater resolution
25380 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 on the profiler
25390 63 61 6c 6c 62 61 63 6b 2e 20 20 49 6e 76 6f 6b callback. Invok
253a0 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 5b 73 ing.** either [s
253b0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 qlite3_trace()]
253c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 or [sqlite3_trac
253d0 65 5f 76 32 28 29 5d 20 77 69 6c 6c 20 63 61 6e e_v2()] will can
253e0 63 65 6c 20 74 68 65 0a 2a 2a 20 70 72 6f 66 69 cel the.** profi
253f0 6c 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2f 0a le callback..*/.
25400 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
25410 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f D void *sqlite3_
25420 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a trace(sqlite3*,.
25430 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 void(*xTrace)
25440 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 (void*,const cha
25450 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c r*), void*);.SQL
25460 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 ITE_DEPRECATED v
25470 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f oid *sqlite3_pro
25480 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 file(sqlite3*,.
25490 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 void(*xProfile
254a0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 )(void*,const ch
254b0 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 ar*,sqlite3_uint
254c0 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 64), void*);../*
254d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 .** CAPI3REF: SQ
254e0 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f L Trace Event Co
254f0 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a des.** KEYWORDS:
25500 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a SQLITE_TRACE.**
25510 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
25520 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61 nts identify cla
25530 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74 sses of events t
25540 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74 hat can be monit
25550 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 ored.** using th
25560 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 e [sqlite3_trace
25570 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c _v2()] tracing l
25580 6f 67 69 63 2e 20 20 54 68 65 20 4d 20 61 72 67 ogic. The M arg
25590 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c ument.** to [sql
255a0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c ite3_trace_v2(D,
255b0 4d 2c 58 2c 50 29 5d 20 69 73 20 61 6e 20 4f 52 M,X,P)] is an OR
255c0 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 -ed combination
255d0 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f of one or more o
255e0 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 f.** the followi
255f0 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e ng constants. ^
25600 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
25610 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 nt to the trace
25620 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f callback.** is o
25630 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
25640 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a ing constants..*
25650 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 *.** New tracing
25660 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 constants may b
25670 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
25680 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a e releases..**.*
25690 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 * ^A trace callb
256a0 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 ack has four arg
256b0 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 uments: xCallbac
256c0 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e k(T,C,P,X)..** ^
256d0 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 The T argument i
256e0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 s one of the int
256f0 65 67 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 eger type codes
25700 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 above..** ^The C
25710 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 argument is a c
25720 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 opy of the conte
25730 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 xt pointer passe
25740 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 d in as the.** f
25750 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 ourth argument t
25760 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 o [sqlite3_trace
25770 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 _v2()]..** The P
25780 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 and X arguments
25790 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 are pointers wh
257a0 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 ose meanings dep
257b0 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 end on T..**.**
257c0 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 <dl>.** [[SQLITE
257d0 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 _TRACE_STMT]] <d
257e0 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 t>SQLITE_TRACE_S
257f0 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TMT</dt>.** <dd>
25800 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 ^An SQLITE_TRACE
25810 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 _STMT callback i
25820 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 s invoked when a
25830 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
25840 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 ent.** first beg
25850 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 ins running and
25860 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 possibly at othe
25870 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 r times during t
25880 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 he.** execution
25890 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 of the prepared
258a0 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 statement, such
258b0 61 73 20 61 74 20 74 68 65 20 73 74 61 72 74 20 as at the start
258c0 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 of each.** trigg
258d0 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e er subprogram. ^
258e0 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 The P argument i
258f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
25900 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
25910 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 statement]. ^The
25920 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 X argument is a
25930 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 pointer to a st
25940 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 ring which.** is
25950 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 the unexpanded
25960 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 SQL text of the
25970 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
25980 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d nt or an SQL com
25990 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e ment .** that in
259a0 64 69 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f dicates the invo
259b0 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 cation of a trig
259c0 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 ger. ^The callb
259d0 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a ack can compute.
259e0 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 ** the same text
259f0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 that would have
25a00 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 been returned b
25a10 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 y the legacy [sq
25a20 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a lite3_trace()].*
25a30 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 * interface by u
25a40 73 69 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d sing the X argum
25a50 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e ent when X begin
25a60 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 s with "--" and
25a70 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c invoking.** [sql
25a80 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 ite3_expanded_sq
25a90 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e l(P)] otherwise.
25aa0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
25ab0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 TRACE_PROFILE]]
25ac0 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 <dt>SQLITE_TRACE
25ad0 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a _PROFILE</dt>.**
25ae0 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f <dd>^An SQLITE_
25af0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 TRACE_PROFILE ca
25b00 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 llback provides
25b10 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 approximately th
25b20 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d e same.** inform
25b30 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 ation as is prov
25b40 69 64 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c ided by the [sql
25b50 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 ite3_profile()]
25b60 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 callback..** ^Th
25b70 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 e P argument is
25b80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
25b90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
25ba0 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a ment] and the.**
25bb0 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e X argument poin
25bc0 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 ts to a 64-bit i
25bd0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 nteger which is
25be0 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 the estimated of
25bf0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
25c00 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 f nanosecond tha
25c10 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 t the prepared s
25c20 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f tatement took to
25c30 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 run..** ^The SQ
25c40 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 LITE_TRACE_PROFI
25c50 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 LE callback is i
25c60 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 nvoked when the
25c70 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 statement finish
25c80 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 es..**.** [[SQLI
25c90 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c TE_TRACE_ROW]] <
25ca0 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f dt>SQLITE_TRACE_
25cb0 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ROW</dt>.** <dd>
25cc0 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 ^An SQLITE_TRACE
25cd0 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 _ROW callback is
25ce0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 invoked wheneve
25cf0 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 r a prepared.**
25d00 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 statement genera
25d10 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 tes a single row
25d20 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a of result. .**
25d30 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 ^The P argument
25d40 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
25d50 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
25d60 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 tatement] and th
25d70 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 e.** X argument
25d80 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a is unused..**.**
25d90 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f [[SQLITE_TRACE_
25da0 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 CLOSE]] <dt>SQLI
25db0 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f TE_TRACE_CLOSE</
25dc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 dt>.** <dd>^An S
25dd0 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 QLITE_TRACE_CLOS
25de0 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e E callback is in
25df0 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 voked when a dat
25e00 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
25e10 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e ion closes..** ^
25e20 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 The P argument i
25e30 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
25e40 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
25e50 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a nection] object.
25e60 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 ** and the X arg
25e70 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e ument is unused.
25e80 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 .** </dl>.*/.#de
25e90 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 fine SQLITE_TRAC
25ea0 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 E_STMT 0x0
25eb0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
25ec0 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 _TRACE_PROFILE
25ed0 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 0x02.#define S
25ee0 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 QLITE_TRACE_ROW
25ef0 20 20 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 0x04.#def
25f00 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 ine SQLITE_TRACE
25f10 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 _CLOSE 0x08
25f20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
25f30 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b : SQL Trace Hook
25f40 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
25f50 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 te3.**.** ^The s
25f60 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 qlite3_trace_v2(
25f70 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 D,M,X,P) interfa
25f80 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 74 ce registers a t
25f90 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a race callback.**
25fa0 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 function X agai
25fb0 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f nst [database co
25fc0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 nnection] D, usi
25fd0 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b ng property mask
25fe0 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 M.** and contex
25ff0 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 t pointer P. ^I
26000 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b f the X callback
26010 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 is.** NULL or i
26020 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 f the M mask is
26030 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 zero, then traci
26040 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 ng is disabled.
26050 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 The.** M argume
26060 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 nt should be the
26070 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 bitwise OR-ed c
26080 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a ombination of.**
26090 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 zero or more [S
260a0 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e QLITE_TRACE] con
260b0 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 stants..**.** ^E
260c0 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 ach call to eith
260d0 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 er sqlite3_trace
260e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 () or sqlite3_tr
260f0 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 ace_v2() overrid
26100 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 es .** (cancels)
26110 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 any prior calls
26120 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 to sqlite3_trac
26130 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 e() or sqlite3_t
26140 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a race_v2()..**.**
26150 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b ^The X callback
26160 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e is invoked when
26170 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 ever any of the
26180 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 events identifie
26190 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 d by .** mask M
261a0 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 occur. ^The int
261b0 65 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 eger return valu
261c0 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 e from the callb
261d0 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 ack is currently
261e0 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f .** ignored, tho
261f0 75 67 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 ugh this may cha
26200 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 nge in future re
26210 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 leases. Callbac
26220 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 k.** implementat
26230 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 ions should retu
26240 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 rn zero to ensur
26250 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 e future compati
26260 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 bility..**.** ^A
26270 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 trace callback
26280 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 is invoked with
26290 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 four arguments:
262a0 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 callback(T,C,P,X
262b0 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 )..** ^The T arg
262c0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 ument is one of
262d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 the [SQLITE_TRAC
262e0 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 E].** constants
262f0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 to indicate why
26300 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 the callback was
26310 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 invoked..** ^Th
26320 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 e C argument is
26330 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f a copy of the co
26340 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a ntext pointer..*
26350 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 * The P and X ar
26360 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e guments are poin
26370 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 ters whose meani
26380 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e ngs depend on T.
26390 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
263a0 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e e3_trace_v2() in
263b0 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e terface is inten
263c0 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 ded to replace t
263d0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 he legacy.** int
263e0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 erfaces [sqlite3
263f0 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 _trace()] and [s
26400 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 qlite3_profile()
26410 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 ], both of which
26420 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 .** are deprecat
26430 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ed..*/.int sqlit
26440 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 e3_trace_v2(. s
26450 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 qlite3*,. unsig
26460 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 ned uMask,. int
26470 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 (*xCallback)(uns
26480 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 igned,void*,void
26490 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 *,void*),. void
264a0 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a *pCtx.);../*.**
264b0 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 CAPI3REF: Query
264c0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 Progress Callba
264d0 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 cks.** METHOD: s
264e0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
264f0 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 e sqlite3_progre
26500 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 ss_handler(D,N,X
26510 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 ,P) interface ca
26520 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 uses the callbac
26530 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 k.** function X
26540 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 to be invoked pe
26550 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e riodically durin
26560 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 g long running c
26570 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 alls to.** [sqli
26580 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 te3_exec()], [sq
26590 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e lite3_step()] an
265a0 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 d [sqlite3_get_t
265b0 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 able()] for.** d
265c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
265d0 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c on D. An exampl
265e0 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a e use for this.*
265f0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 * interface is t
26600 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 o keep a GUI upd
26610 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 ated during a la
26620 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a rge query..**.**
26630 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 ^The parameter
26640 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f P is passed thro
26650 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 ugh as the only
26660 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
26670 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 .** callback fu
26680 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 nction X. ^The
26690 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 parameter N is t
266a0 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e he approximate n
266b0 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 umber of .** [vi
266c0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e rtual machine in
266d0 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 structions] that
266e0 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 are evaluated b
266f0 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 etween successiv
26700 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 e.** invocations
26710 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b of the callback
26720 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 X. ^If N is le
26730 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e ss than one then
26740 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a the progress.**
26750 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 handler is disa
26760 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c bled..**.** ^Onl
26770 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 y a single progr
26780 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 ess handler may
26790 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e be defined at on
267a0 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 e time per.** [d
267b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
267c0 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e on]; setting a n
267d0 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 ew progress hand
267e0 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a ler cancels the.
267f0 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 ** old one. ^Se
26800 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 tting parameter
26810 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c X to NULL disabl
26820 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 es the progress
26830 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 handler..** ^The
26840 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
26850 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c r is also disabl
26860 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 ed by setting N
26870 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a to a value less.
26880 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a ** than 1..**.**
26890 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 ^If the progres
268a0 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 s callback retur
268b0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
268c0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a operation is.**
268d0 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 interrupted. T
268e0 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 his feature can
268f0 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 be used to imple
26900 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 ment a.** "Cance
26910 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 l" button on a G
26920 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c UI progress dial
26930 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 og box..**.** Th
26940 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
26950 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 er callback must
26960 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 not do anything
26970 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 that will modif
26980 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 y.** the databas
26990 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 e connection tha
269a0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 t invoked the pr
269b0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a ogress handler..
269c0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 ** Note that [sq
269d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
269e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
269f0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f _step()] both mo
26a00 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 dify their.** da
26a10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
26a20 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 ns for the meani
26a30 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 ng of "modify" i
26a40 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 n this paragraph
26a50 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c ..**.*/.void sql
26a60 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 ite3_progress_ha
26a70 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 ndler(sqlite3*,
26a80 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 int, int(*)(void
26a90 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a *), void*);../*.
26aa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 ** CAPI3REF: Ope
26ab0 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 ning A New Datab
26ac0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase Connection.*
26ad0 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 * CONSTRUCTOR: s
26ae0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
26af0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 ese routines ope
26b00 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 n an SQLite data
26b10 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 base file as spe
26b20 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a cified by the .*
26b30 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d * filename argum
26b40 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 ent. ^The filena
26b50 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 me argument is i
26b60 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 nterpreted as UT
26b70 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 F-8 for.** sqlit
26b80 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
26b90 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
26ba0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e and as UTF-16 in
26bb0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
26bc0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 .** order for sq
26bd0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 lite3_open16().
26be0 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f ^(A [database co
26bf0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 nnection] handle
26c00 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 is usually.** r
26c10 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 eturned in *ppDb
26c20 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 , even if an err
26c30 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 or occurs. The
26c40 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 only exception i
26c50 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c s that.** if SQL
26c60 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ite is unable to
26c70 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 allocate memory
26c80 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 to hold the [sq
26c90 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a lite3] object,.*
26ca0 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 * a NULL will be
26cb0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 written into *p
26cc0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 pDb instead of a
26cd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
26ce0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a [sqlite3].** obj
26cf0 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 ect.)^ ^(If the
26d00 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
26d10 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 ed (and/or creat
26d20 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 ed) successfully
26d30 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 , then.** [SQLIT
26d40 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 E_OK] is returne
26d50 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e d. Otherwise an
26d60 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
26d70 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 returned.)^ ^Th
26d80 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 e.** [sqlite3_er
26d90 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 rmsg()] or [sqli
26da0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 te3_errmsg16()]
26db0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 routines can be
26dc0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a used to obtain.*
26dd0 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e * an English lan
26de0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f guage descriptio
26df0 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 n of the error f
26e00 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 ollowing a failu
26e10 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 re of any.** of
26e20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e the sqlite3_open
26e30 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a () routines..**.
26e40 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 ** ^The default
26e50 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 encoding will be
26e60 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 UTF-8 for datab
26e70 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69 ases created usi
26e80 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 ng.** sqlite3_op
26e90 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f en() or sqlite3_
26ea0 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 open_v2(). ^The
26eb0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e default encodin
26ec0 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a g for databases.
26ed0 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 ** created using
26ee0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
26ef0 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 ) will be UTF-16
26f00 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 in the native b
26f10 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a yte order..**.**
26f20 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 Whether or not
26f30 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 an error occurs
26f40 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 when it is opene
26f50 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 d, resources.**
26f60 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
26f70 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
26f80 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 nnection] handle
26f90 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 should be relea
26fa0 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e sed by.** passin
26fb0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 g it to [sqlite3
26fc0 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 _close()] when i
26fd0 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 t is no longer r
26fe0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 equired..**.** T
26ff0 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f he sqlite3_open_
27000 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 v2() interface w
27010 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 orks like sqlite
27020 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 3_open().** exce
27030 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 pt that it accep
27040 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 ts two additiona
27050 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 l parameters for
27060 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 additional cont
27070 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 rol.** over the
27080 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e new database con
27090 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 nection. ^(The
270a0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 flags parameter
270b0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 to.** sqlite3_op
270c0 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 en_v2() can take
270d0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 one of.** the f
270e0 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 ollowing three v
270f0 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c alues, optionall
27100 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 y combined with
27110 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the .** [SQLITE_
27120 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b OPEN_NOMUTEX], [
27130 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c SQLITE_OPEN_FULL
27140 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f MUTEX], [SQLITE_
27150 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
27160 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 ],.** [SQLITE_OP
27170 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d EN_PRIVATECACHE]
27180 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 , and/or [SQLITE
27190 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 _OPEN_URI] flags
271a0 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a :)^.**.** <dl>.*
271b0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f * ^(<dt>[SQLITE_
271c0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f OPEN_READONLY]</
271d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 dt>.** <dd>The d
271e0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
271f0 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d d in read-only m
27200 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 ode. If the dat
27210 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a abase does not.*
27220 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c * already exist,
27230 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 an error is ret
27240 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a urned.</dd>)^.**
27250 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 .** ^(<dt>[SQLIT
27260 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
27270 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 ]</dt>.** <dd>Th
27280 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
27290 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 ened for reading
272a0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 and writing if
272b0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 possible, or rea
272c0 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 ding.** only if
272d0 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 the file is writ
272e0 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 e protected by t
272f0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
27300 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a tem. In either.
27310 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 ** case the data
27320 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 base must alread
27330 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 y exist, otherwi
27340 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 se an error is r
27350 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a eturned.</dd>)^.
27360 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c **.** ^(<dt>[SQL
27370 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
27380 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 TE] | [SQLITE_OP
27390 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a EN_CREATE]</dt>.
273a0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 ** <dd>The datab
273b0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f ase is opened fo
273c0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 r reading and wr
273d0 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 iting, and is cr
273e0 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 eated if.** it d
273f0 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 oes not already
27400 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 exist. This is t
27410 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 he behavior that
27420 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 is always used
27430 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f for.** sqlite3_o
27440 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 pen() and sqlite
27450 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 3_open16().</dd>
27460 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a )^.** </dl>.**.*
27470 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 * If the 3rd par
27480 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
27490 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 3_open_v2() is n
274a0 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a ot one of the.**
274b0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 combinations sh
274c0 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e own above option
274d0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 ally combined wi
274e0 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c th other.** [SQL
274f0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
27500 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f Y | SQLITE_OPEN_
27510 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 * bits].** then
27520 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
27530 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
27540 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 ^If the [SQLITE
27550 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 _OPEN_NOMUTEX] f
27560 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e lag is set, then
27570 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
27580 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e nnection.** open
27590 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 s in the multi-t
275a0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 hread [threading
275b0 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 mode] as long a
275c0 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 s the single-thr
275d0 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 ead.** mode has
275e0 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 not been set at
275f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 compile-time or
27600 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 start-time. ^If
27610 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
27620 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 OPEN_FULLMUTEX]
27630 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e flag is set then
27640 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
27650 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a nnection opens.*
27660 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 * in the seriali
27670 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d zed [threading m
27680 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 ode] unless sing
27690 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a le-thread was.**
276a0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 previously sele
276b0 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d cted at compile-
276c0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 time or start-ti
276d0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c me..** ^The [SQL
276e0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
276f0 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 ACHE] flag cause
27700 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 s the database c
27710 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a onnection to be.
27720 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 ** eligible to u
27730 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 se [shared cache
27740 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 mode], regardle
27750 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ss of whether or
27760 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 not shared.** c
27770 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 ache is enabled
27780 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 using [sqlite3_e
27790 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 nable_shared_cac
277a0 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 he()]. ^The.**
277b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 [SQLITE_OPEN_PRI
277c0 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 VATECACHE] flag
277d0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 causes the datab
277e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
277f0 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 o not.** partici
27800 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 pate in [shared
27810 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e cache mode] even
27820 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 if it is enable
27830 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f d..**.** ^The fo
27840 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
27850 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
27860 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 2() is the name
27870 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 of the.** [sqlit
27880 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 e3_vfs] object t
27890 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 hat defines the
278a0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
278b0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a interface that.
278c0 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 ** the new datab
278d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 ase connection s
278e0 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 hould use. ^If
278f0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
27900 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c eter is.** a NUL
27910 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 L pointer then t
27920 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 he default [sqli
27930 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 te3_vfs] object
27940 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e is used..**.** ^
27950 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 If the filename
27960 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 is ":memory:", t
27970 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 hen a private, t
27980 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f emporary in-memo
27990 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 ry database.** i
279a0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 s created for th
279b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e e connection. ^
279c0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 This in-memory d
279d0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e atabase will van
279e0 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 ish when.** the
279f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
27a00 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 ion is closed.
27a10 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 Future versions
27a20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a of SQLite might.
27a30 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 ** make use of a
27a40 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 dditional specia
27a50 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 l filenames that
27a60 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 begin with the
27a70 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ":" character..*
27a80 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e * It is recommen
27a90 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 ded that when a
27aa0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d database filenam
27ab0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 e actually does
27ac0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 begin with.** a
27ad0 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f ":" character yo
27ae0 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 u should prefix
27af0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 the filename wit
27b00 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 h a pathname suc
27b10 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 h as.** "./" to
27b20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e avoid ambiguity.
27b30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .**.** ^If the f
27b40 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d ilename is an em
27b50 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e pty string, then
27b60 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 a private, temp
27b70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b orary.** on-disk
27b80 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 database will b
27b90 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 e created. ^Thi
27ba0 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 s private databa
27bb0 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 se will be.** au
27bc0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 tomatically dele
27bd0 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 ted as soon as t
27be0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
27bf0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 ection is closed
27c00 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 ..**.** [[URI fi
27c10 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 lenames in sqlit
27c20 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e e3_open()]] <h3>
27c30 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 URI Filenames</h
27c40 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 3>.**.** ^If [UR
27c50 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 I filename] inte
27c60 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e rpretation is en
27c70 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 abled, and the f
27c80 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
27c90 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 .** begins with
27ca0 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 "file:", then th
27cb0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e e filename is in
27cc0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 terpreted as a U
27cd0 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 RI. ^URI.** file
27ce0 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 name interpretat
27cf0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 ion is enabled i
27d00 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 f the [SQLITE_OP
27d10 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a EN_URI] flag is.
27d20 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 74 68 ** set in the th
27d30 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ird argument to
27d40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
27d50 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a ), or if it has.
27d60 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 ** been enabled
27d70 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 globally using t
27d80 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 he [SQLITE_CONFI
27d90 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 G_URI] option wi
27da0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 th the.** [sqlit
27db0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 e3_config()] met
27dc0 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 hod or by the [S
27dd0 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 QLITE_USE_URI] c
27de0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
27df0 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e on..** URI filen
27e00 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 ame interpretati
27e10 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 on is turned off
27e20 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 .** by default,
27e30 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 but future relea
27e40 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 ses of SQLite mi
27e50 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 ght enable URI f
27e60 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 ilename.** inter
27e70 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 pretation by def
27e80 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 ault. See "[URI
27e90 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 filenames]" for
27ea0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 additional.** i
27eb0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
27ec0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 * URI filenames
27ed0 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 are parsed accor
27ee0 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 ding to RFC 3986
27ef0 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f . ^If the URI co
27f00 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 ntains an.** aut
27f10 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 hority, then it
27f20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 must be either a
27f30 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f n empty string o
27f40 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a r the string .**
27f50 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 "localhost". ^I
27f60 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 f the authority
27f70 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 is not an empty
27f80 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c string or "local
27f90 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 host", an .** er
27fa0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 ror is returned
27fb0 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e to the caller. ^
27fc0 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d The fragment com
27fd0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c ponent of a URI,
27fe0 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c if .** present,
27ff0 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a is ignored..**.
28000 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 ** ^SQLite uses
28010 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 the path compone
28020 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 nt of the URI as
28030 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
28040 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 disk file.** wh
28050 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 ich contains the
28060 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 database. ^If t
28070 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 he path begins w
28080 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 ith a '/' charac
28090 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 ter, .** then it
280a0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
280b0 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 as an absolute p
280c0 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 ath. ^If the pat
280d0 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e h does not begin
280e0 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 .** with a '/'
280f0 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 (meaning that th
28100 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 e authority sect
28110 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 ion is omitted f
28120 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 rom the URI).**
28130 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 then the path is
28140 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
28150 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e a relative path.
28160 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 .** ^(On window
28170 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d s, the first com
28180 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 ponent of an abs
28190 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 olute path .** i
281a0 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 s a drive specif
281b0 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 ication (e.g. "C
281c0 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 :").)^.**.** [[c
281d0 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 ore URI query pa
281e0 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 rameters]].** Th
281f0 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e e query componen
28200 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 t of a URI may c
28210 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 ontain parameter
28220 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 s that are inter
28230 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 preted.** either
28240 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c by SQLite itsel
28250 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 f, or by a [VFS
28260 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 | custom VFS imp
28270 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a lementation]..**
28280 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 SQLite and its
28290 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d built-in [VFSes]
282a0 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a interpret the.*
282b0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 * following quer
282c0 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a y parameters:.**
282d0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c .** <ul>.** <l
282e0 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e i> <b>vfs</b>: ^
282f0 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 The "vfs" parame
28300 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 ter may be used
28310 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e to specify the n
28320 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 ame of.** a
28330 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 VFS object that
28340 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 provides the ope
28350 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e rating system in
28360 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f terface that sho
28370 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 uld.** be us
28380 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 ed to access the
28390 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f database file o
283a0 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 n disk. ^If this
283b0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 option is set t
283c0 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 o.** an empt
283d0 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 y string the def
283e0 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 ault VFS object
283f0 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 is used. ^Specif
28400 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a ying an unknown.
28410 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e ** VFS is an
28420 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 error. ^If sqli
28430 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
28440 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 used and the vf
28450 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 s option is.**
28460 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e present, then
28470 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 the VFS specifi
28480 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e ed by the option
28490 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 takes precedenc
284a0 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 e over.** th
284b0 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 e value passed a
284c0 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 s the fourth par
284d0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
284e0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 3_open_v2()..**.
284f0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 ** <li> <b>mod
28500 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 e</b>: ^(The mod
28510 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 e parameter may
28520 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 be set to either
28530 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 "ro", "rw",.**
28540 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d "rwc", or "m
28550 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 emory". Attempti
28560 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 ng to set it to
28570 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 any other value
28580 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 is.** an err
28590 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 or)^. .** ^I
285a0 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 f "ro" is specif
285b0 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 ied, then the da
285c0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
285d0 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a for read-only .
285e0 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a ** access, j
285f0 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 ust as if the [S
28600 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
28610 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 NLY] flag had be
28620 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a en set in the .*
28630 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 * third argu
28640 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
28650 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 open_v2(). ^If t
28660 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 he mode option i
28670 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 s set to .**
28680 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 "rw", then the
28690 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
286a0 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 ed for read-writ
286b0 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 e (but not creat
286c0 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 e) .** acces
286d0 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f s, as if SQLITE_
286e0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 OPEN_READWRITE (
286f0 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f but not SQLITE_O
28700 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 PEN_CREATE) had
28710 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 .** been set
28720 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 . ^Value "rwc" i
28730 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 s equivalent to
28740 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a setting both .**
28750 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e SQLITE_OPEN
28760 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 _READWRITE and S
28770 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
28780 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 E. ^If the mode
28790 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 option is.**
287a0 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 set to "memory
287b0 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 " then a pure [i
287c0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 n-memory databas
287d0 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 e] that never re
287e0 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 ads.** or wr
287f0 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 ites from disk i
28800 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 s used. ^It is a
28810 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 n error to speci
28820 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a fy a value for.*
28830 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 * the mode p
28840 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 arameter that is
28850 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 less restrictiv
28860 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 e than that spec
28870 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 ified by.**
28880 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 the flags passed
28890 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 in the third pa
288a0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
288b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a e3_open_v2()..**
288c0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 .** <li> <b>ca
288d0 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 che</b>: ^The ca
288e0 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 che parameter ma
288f0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 y be set to eith
28900 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a er "shared" or.*
28910 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e * "private".
28920 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 ^Setting it to
28930 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 "shared" is equi
28940 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e valent to settin
28950 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c g the.** SQL
28960 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
28970 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 ACHE bit in the
28980 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 flags argument p
28990 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 assed to.**
289a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
289b0 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 ). ^Setting the
289c0 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 cache parameter
289d0 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 to "private" is
289e0 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 .** equivale
289f0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 nt to setting th
28a00 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 e SQLITE_OPEN_PR
28a10 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a IVATECACHE bit..
28a20 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 ** ^If sqlit
28a30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
28a40 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 used and the "ca
28a50 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 che" parameter i
28a60 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 s present in.**
28a70 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 a URI filena
28a80 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 me, its value ov
28a90 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 errides any beha
28aa0 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 vior requested b
28ab0 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 y setting.**
28ac0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 SQLITE_OPEN_PRI
28ad0 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c VATECACHE or SQL
28ae0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
28af0 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a ACHE flag..**.**
28b00 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f <li> <b>psow</
28b10 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 b>: ^The psow pa
28b20 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 rameter indicate
28b30 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 s whether or not
28b40 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 the.** [pow
28b50 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 ersafe overwrite
28b60 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 ] property does
28b70 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c or does not appl
28b80 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 y to the.**
28b90 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e storage media on
28ba0 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62 which the datab
28bb0 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 ase file resides
28bc0 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 ..**.** <li> <b
28bd0 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 >nolock</b>: ^Th
28be0 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 e nolock paramet
28bf0 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 er is a boolean
28c00 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a query parameter.
28c10 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20 ** which if
28c20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c set disables fil
28c30 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c e locking in rol
28c40 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f lback journal mo
28c50 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 des. This.**
28c60 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 is useful for
28c70 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 accessing a data
28c80 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 base on a filesy
28c90 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e stem that does n
28ca0 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 ot.** suppor
28cb0 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 t locking. Caut
28cc0 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 ion: Database c
28cd0 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 orruption might
28ce0 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a result if two.**
28cf0 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f or more pro
28d00 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 cesses write to
28d10 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
28d20 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 e and any one of
28d30 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 those.** pr
28d40 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c ocesses uses nol
28d50 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c ock=1..**.** <l
28d60 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c i> <b>immutable<
28d70 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 /b>: ^The immuta
28d80 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 ble parameter is
28d90 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 a boolean query
28da0 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 .** paramete
28db0 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 r that indicates
28dc0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 that the databa
28dd0 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 se file is store
28de0 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 d on.** read
28df0 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 -only media. ^W
28e00 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 hen immutable is
28e10 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 set, SQLite ass
28e20 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a umes that the.**
28e30 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69 database fi
28e40 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 le cannot be cha
28e50 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 nged, even by a
28e60 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 process with hig
28e70 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 her.** privi
28e80 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 lege, and so the
28e90 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
28ea0 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e ned read-only an
28eb0 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a d all locking.**
28ec0 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 and change
28ed0 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 detection is dis
28ee0 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a abled. Caution:
28ef0 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d Setting the imm
28f00 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 utable.** pr
28f10 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 operty on a data
28f20 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 base file that d
28f30 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e oes in fact chan
28f40 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a ge can result.**
28f50 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 in incorrec
28f60 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 t query results
28f70 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 and/or [SQLITE_C
28f80 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a ORRUPT] errors..
28f90 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a ** See also:
28fa0 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 [SQLITE_IOCAP_I
28fb0 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 MMUTABLE]..**
28fc0 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a .** </ul>.**
28fd0 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 .** ^Specifying
28fe0 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d an unknown param
28ff0 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 eter in the quer
29000 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 y component of a
29010 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a URI is not an.*
29020 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 * error. Future
29030 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
29040 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 ite might unders
29050 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 tand additional
29060 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 query.** paramet
29070 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 ers. See "[quer
29080 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 y parameters wit
29090 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e h special meanin
290a0 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f g to SQLite]" fo
290b0 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 r.** additional
290c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
290d0 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d ** [[URI filenam
290e0 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 e examples]] <h3
290f0 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 >URI filename ex
29100 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a amples</h3>.**.*
29110 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d * <table border=
29120 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 "1" align=center
29130 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a cellpadding=5>.
29140 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 ** <tr><th> URI
29150 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 filenames <th> R
29160 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 esults.** <tr><t
29170 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 d> file:data.db
29180 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 <td> .**
29190 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 Open the file
291a0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 "data.db" in the
291b0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f current directo
291c0 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ry..** <tr><td>
291d0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f file:/home/fred/
291e0 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 data.db<br>.**
291f0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f file:///
29200 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
29210 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 b <br> .**
29220 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c file://local
29230 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 host/home/fred/d
29240 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e ata.db <br> <td>
29250 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 .** Op
29260 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
29270 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 file "/home/fred
29280 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 /data.db"..** <t
29290 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 r><td> file://da
292a0 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 rkstar/home/fred
292b0 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a /data.db <td> .*
292c0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 * An er
292d0 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 ror. "darkstar"
292e0 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 is not a recogni
292f0 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a zed authority..*
29300 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d * <tr><td style=
29310 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 "white-space:now
29320 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 rap"> .**
29330 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f file:///C:/Do
29340 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 cuments%20and%20
29350 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 Settings/fred/De
29360 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a sktop/data.db.**
29370 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 <td> Window
29380 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 s only: Open the
29390 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 file "data.db"
293a0 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f on fred's deskto
293b0 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 p on drive.**
293c0 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 C:. Note
293d0 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 that the %20 esc
293e0 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 aping in this ex
293f0 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 ample is not str
29400 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 ictly .**
29410 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 necessary - s
29420 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 pace characters
29430 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 can be used lite
29440 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 rally.**
29450 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d in URI filenam
29460 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 es..** <tr><td>
29470 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 file:data.db?mod
29480 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 e=ro&cache=priva
29490 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 te <td> .**
294a0 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 Open file "
294b0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 data.db" in the
294c0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 current director
294d0 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 y for read-only
294e0 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 access..**
294f0 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f Regardless o
29500 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
29510 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f shared-cache mo
29520 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 de is enabled by
29530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 .** def
29540 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 ault, use a priv
29550 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 ate cache..** <t
29560 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d r><td> file:/hom
29570 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 e/fred/data.db?v
29580 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 fs=unix-dotfile
29590 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 <td>.**
295a0 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d Open file "/hom
295b0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e e/fred/data.db".
295c0 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c Use the special
295d0 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 VFS "unix-dotfi
295e0 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 le".**
295f0 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 that uses dot-fi
29600 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 les in place of
29610 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c posix advisory l
29620 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c ocking..** <tr><
29630 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 td> file:data.db
29640 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c ?mode=readonly <
29650 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 td> .**
29660 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 An error. "read
29670 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 only" is not a v
29680 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 alid option for
29690 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d the "mode" param
296a0 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 eter..** </table
296b0 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 >.**.** ^URI hex
296c0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 adecimal escape
296d0 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 sequences (%HH)
296e0 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 are supported wi
296f0 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e thin the path an
29700 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f d.** query compo
29710 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 nents of a URI.
29720 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 A hexadecimal es
29730 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f cape sequence co
29740 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 nsists of a.** p
29750 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 ercent sign - "%
29760 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 " - followed by
29770 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 exactly two hexa
29780 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a decimal digits .
29790 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e ** specifying an
297a0 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 octet value. ^B
297b0 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f efore the path o
297c0 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e r query componen
297d0 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 ts of a.** URI f
297e0 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 ilename are inte
297f0 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 rpreted, they ar
29800 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 e encoded using
29810 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a UTF-8 and all .*
29820 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 * hexadecimal es
29830 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 cape sequences r
29840 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e eplaced by a sin
29850 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e gle byte contain
29860 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 ing the.** corre
29870 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 sponding octet.
29880 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 If this process
29890 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 generates an inv
298a0 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 alid UTF-8 encod
298b0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 ing,.** the resu
298c0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
298d0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 d..**.** <b>Note
298e0 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 to Windows user
298f0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f s:</b> The enco
29900 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 ding used for th
29910 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d e filename argum
29920 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 ent.** of sqlite
29930 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 3_open() and sql
29940 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d ite3_open_v2() m
29950 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f ust be UTF-8, no
29960 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f t whatever.** co
29970 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e depage is curren
29980 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 tly defined. Fi
29990 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 lenames containi
299a0 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c ng international
299b0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d .** characters m
299c0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 ust be converted
299d0 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 to UTF-8 prior
299e0 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 to passing them
299f0 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f into.** sqlite3_
29a00 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 open() or sqlite
29a10 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 3_open_v2()..**.
29a20 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 ** <b>Note to Wi
29a30 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 ndows Runtime us
29a40 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 ers:</b> The te
29a50 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 mporary director
29a60 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a y must be set.**
29a70 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e prior to callin
29a80 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 g sqlite3_open()
29a90 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e or sqlite3_open
29aa0 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 _v2(). Otherwis
29ab0 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 e, various.** fe
29ac0 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 atures that requ
29ad0 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 ire the use of t
29ae0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d emporary files m
29af0 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 ay fail..**.** S
29b00 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
29b10 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3_temp_directory
29b20 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
29b30 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 _open(. const c
29b40 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 har *filename,
29b50 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
29b60 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f ename (UTF-8) */
29b70 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 . sqlite3 **ppD
29b80 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 b /* OU
29b90 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e T: SQLite db han
29ba0 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 dle */.);.int sq
29bb0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 lite3_open16(.
29bc0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 const void *file
29bd0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
29be0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
29bf0 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 F-16) */. sqlit
29c00 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 e3 **ppDb
29c10 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 /* OUT: SQLit
29c20 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 e db handle */.)
29c30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 ;.int sqlite3_op
29c40 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 en_v2(. const c
29c50 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 har *filename,
29c60 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
29c70 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f ename (UTF-8) */
29c80 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 . sqlite3 **ppD
29c90 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 b, /* OU
29ca0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e T: SQLite db han
29cb0 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 dle */. int fla
29cc0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 gs,
29cd0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 /* Flags */. c
29ce0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 onst char *zVfs
29cf0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f /* Name o
29d00 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 f VFS module to
29d10 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a use */.);../*.**
29d20 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 CAPI3REF: Obtai
29d30 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 n Values For URI
29d40 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a Parameters.**.*
29d50 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c * These are util
29d60 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 ity routines, us
29d70 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c eful to VFS impl
29d80 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 ementations, tha
29d90 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 t check.** to se
29da0 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 e if a database
29db0 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 file was a URI t
29dc0 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 hat contained a
29dd0 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a specific query .
29de0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e ** parameter, an
29df0 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 d if so obtains
29e00 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 the value of tha
29e10 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 t query paramete
29e20 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 r..**.** If F is
29e30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
29e40 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 lename pointer p
29e50 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 assed into the x
29e60 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 Open() method of
29e70 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 .** a VFS imple
29e80 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 mentation when t
29e90 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 he flags paramet
29ea0 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 er to xOpen() ha
29eb0 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 s one or .** mor
29ec0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 e of the [SQLITE
29ed0 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 _OPEN_URI] or [S
29ee0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
29ef0 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 DB] bits set and
29f00 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d .** P is the nam
29f10 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 e of the query p
29f20 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a arameter, then.*
29f30 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 * sqlite3_uri_pa
29f40 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 rameter(F,P) ret
29f50 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f urns the value o
29f60 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d f the P.** param
29f70 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 eter if it exist
29f80 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e s or a NULL poin
29f90 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f ter if P does no
29fa0 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a t appear as a .*
29fb0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 * query paramete
29fc0 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 r on F. If P is
29fd0 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 a query paramet
29fe0 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e er of F.** has n
29ff0 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 o explicit value
2a000 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 , then sqlite3_u
2a010 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 ri_parameter(F,P
2a020 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 ) returns.** a p
2a030 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 ointer to an emp
2a040 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a ty string..**.**
2a050 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 The sqlite3_uri
2a060 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
2a070 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 routine assumes
2a080 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c that P is a bool
2a090 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ean.** parameter
2a0a0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 and returns tru
2a0b0 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 e (1) or false (
2a0c0 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 0) according to
2a0d0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 the value.** of
2a0e0 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f P. The sqlite3_
2a0f0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
2a100 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 B) routine retur
2a110 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 ns true (1) if t
2a120 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 he.** value of q
2a130 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 uery parameter P
2a140 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 is one of "yes"
2a150 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e , "true", or "on
2a160 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 " in any.** case
2a170 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 or if the value
2a180 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e begins with a n
2a190 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 on-zero number.
2a1a0 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 The .** sqlite3
2a1b0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 _uri_boolean(F,P
2a1c0 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ,B) routines ret
2a1d0 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 urns false (0) i
2a1e0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a f the value of.*
2a1f0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 * query paramete
2a200 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e r P is one of "n
2a210 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 o", "false", or
2a220 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 "off" in any cas
2a230 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 e or.** if the v
2a240 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 alue begins with
2a250 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e a numeric zero.
2a260 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 If P is not a
2a270 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 query.** paramet
2a280 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 er on F or if th
2a290 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 e value of P is
2a2a0 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 does not match a
2a2b0 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f ny of the.** abo
2a2c0 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ve, then sqlite3
2a2d0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 _uri_boolean(F,P
2a2e0 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d ,B) returns (B!=
2a2f0 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 0)..**.** The sq
2a300 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 lite3_uri_int64(
2a310 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 F,P,D) routine c
2a320 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 onverts the valu
2a330 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a e of P into a.**
2a340 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
2a350 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 nteger and retur
2a360 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c ns that integer,
2a370 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 or D if P does
2a380 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 not.** exist. I
2a390 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 f the value of P
2a3a0 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 is something ot
2a3b0 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 her than an inte
2a3c0 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 ger, then.** zer
2a3d0 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a o is returned..*
2a3e0 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 * .** If F is a
2a3f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 NULL pointer, th
2a400 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 en sqlite3_uri_p
2a410 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 arameter(F,P) re
2a420 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a turns NULL and.*
2a430 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f * sqlite3_uri_bo
2a440 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 olean(F,P,B) ret
2a450 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 urns B. If F is
2a460 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e not a NULL poin
2a470 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f ter and.** is no
2a480 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c t a database fil
2a490 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 e pathname point
2a4a0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 er that SQLite p
2a4b0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 assed into the x
2a4c0 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 Open.** VFS meth
2a4d0 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 od, then the beh
2a4e0 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f avior of this ro
2a4f0 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e utine is undefin
2a500 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a ed and probably.
2a510 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a ** undesirable..
2a520 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 55 **.** See the [U
2a530 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 64 6f 63 RI filename] doc
2a540 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 umentation for a
2a550 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
2a560 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 ation..*/.const
2a570 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 char *sqlite3_ur
2a580 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 i_parameter(cons
2a590 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d t char *zFilenam
2a5a0 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a e, const char *z
2a5b0 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 Param);.int sqli
2a5c0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
2a5d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c const char *zFil
2a5e0 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a e, const char *z
2a5f0 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 Param, int bDefa
2a600 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e ult);.sqlite3_in
2a610 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f t64 sqlite3_uri_
2a620 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 int64(const char
2a630 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 *, const char*,
2a640 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
2a650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2a660 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e : Error Codes An
2a670 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 d Messages.** ME
2a680 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
2a690 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 .** ^If the most
2a6a0 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f recent sqlite3_
2a6b0 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 * API call assoc
2a6c0 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b iated with .** [
2a6d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2a6e0 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 ion] D failed, t
2a6f0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f hen the sqlite3_
2a700 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72 errcode(D) inter
2a710 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 face.** returns
2a720 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 the numeric [res
2a730 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 ult code] or [ex
2a740 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
2a750 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 de] for that.**
2a760 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 5e 54 68 API call..** ^Th
2a770 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 e sqlite3_extend
2a780 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 ed_errcode().**
2a790 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 interface is the
2a7a0 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 same except tha
2a7b0 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 t it always retu
2a7c0 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 rns the .** [ext
2a7d0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
2a7e0 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 e] even when ext
2a7f0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
2a800 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c es are.** disabl
2a810 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 ed..**.** The va
2a820 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 lues returned by
2a830 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
2a840 28 29 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c () and/or.** sql
2a850 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 ite3_extended_er
2a860 72 63 6f 64 65 28 29 20 6d 69 67 68 74 20 63 68 rcode() might ch
2a870 61 6e 67 65 20 77 69 74 68 20 65 61 63 68 20 41 ange with each A
2a880 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 45 78 63 65 PI call..** Exce
2a890 70 74 2c 20 74 68 65 72 65 20 61 72 65 20 73 6f pt, there are so
2a8a0 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 68 me interfaces th
2a8b0 61 74 20 61 72 65 20 67 75 61 72 61 6e 74 65 65 at are guarantee
2a8c0 64 20 74 6f 20 6e 65 76 65 72 0a 2a 2a 20 63 68 d to never.** ch
2a8d0 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 6f ange the value o
2a8e0 66 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 f the error code
2a8f0 2e 20 20 54 68 65 20 65 72 72 6f 72 2d 63 6f 64 . The error-cod
2a900 65 20 70 72 65 73 65 72 76 69 6e 67 0a 2a 2a 20 e preserving.**
2a910 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 3a 0a interfaces are:.
2a920 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
2a930 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f i> sqlite3_errco
2a940 64 65 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c de().** <li> sql
2a950 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 ite3_extended_er
2a960 72 63 6f 64 65 28 29 0a 2a 2a 20 3c 6c 69 3e 20 rcode().** <li>
2a970 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
2a980 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 .** <li> sqlite3
2a990 5f 65 72 72 6d 73 67 31 36 28 29 0a 2a 2a 20 3c _errmsg16().** <
2a9a0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 /ul>.**.** ^The
2a9b0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
2a9c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 and sqlite3_err
2a9d0 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 msg16() return E
2a9e0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a nglish-language.
2a9f0 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 ** text that des
2aa00 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 cribes the error
2aa10 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d , as either UTF-
2aa20 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 8 or UTF-16 resp
2aa30 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d ectively..** ^(M
2aa40 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
2aa50 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
2aa60 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 string is manage
2aa70 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a d internally..**
2aa80 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
2aa90 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
2aaa0 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 o worry about fr
2aab0 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 eeing the result
2aac0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 ..** However, th
2aad0 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d e error string m
2aae0 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 ight be overwrit
2aaf0 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 ten or deallocat
2ab00 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 ed by.** subsequ
2ab10 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 ent calls to oth
2ab20 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
2ab30 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e ace functions.)^
2ab40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2ab50 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 te3_errstr() int
2ab60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
2ab70 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 he English-langu
2ab80 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 age text.** that
2ab90 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b describes the [
2aba0 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 result code], as
2abb0 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d UTF-8..** ^(Mem
2abc0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 ory to hold the
2abd0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 error message st
2abe0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 ring is managed
2abf0 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e internally.** an
2ac00 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 d must not be fr
2ac10 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 eed by the appli
2ac20 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 cation)^..**.**
2ac30 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 When the seriali
2ac40 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d zed [threading m
2ac50 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 ode] is in use,
2ac60 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a it might be the.
2ac70 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 ** case that a s
2ac80 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 econd error occu
2ac90 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 rs on a separate
2aca0 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 thread in betwe
2acb0 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f en.** the time o
2acc0 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f f the first erro
2acd0 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 r and the call t
2ace0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 o these interfac
2acf0 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 es..** When that
2ad00 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 happens, the se
2ad10 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 cond error will
2ad20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 be reported sinc
2ad30 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 e these.** inter
2ad40 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 faces always rep
2ad50 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ort the most rec
2ad60 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 ent result. To
2ad70 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 avoid.** this, e
2ad80 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f ach thread can o
2ad90 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 btain exclusive
2ada0 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 use of the [data
2adb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2adc0 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e D.** by invokin
2add0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 g [sqlite3_mutex
2ade0 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 _enter]([sqlite3
2adf0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 _db_mutex](D)) b
2ae00 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a efore beginning.
2ae10 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 ** to use D and
2ae20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 invoking [sqlite
2ae30 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 3_mutex_leave]([
2ae40 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 sqlite3_db_mutex
2ae50 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 ](D)) after.** a
2ae60 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 ll calls to the
2ae70 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 interfaces liste
2ae80 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c d here are compl
2ae90 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 eted..**.** If a
2aea0 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c n interface fail
2aeb0 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 s with SQLITE_MI
2aec0 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 SUSE, that means
2aed0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a the interface.*
2aee0 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e * was invoked in
2aef0 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 correctly by the
2af00 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 application. I
2af10 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 n that case, the
2af20 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 .** error code a
2af30 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f nd message may o
2af40 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 r may not be set
2af50 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2af60 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 _errcode(sqlite3
2af70 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 *db);.int sqlit
2af80 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 e3_extended_errc
2af90 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 ode(sqlite3 *db)
2afa0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 ;.const char *sq
2afb0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c lite3_errmsg(sql
2afc0 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f ite3*);.const vo
2afd0 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d id *sqlite3_errm
2afe0 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a sg16(sqlite3*);.
2aff0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
2b000 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b te3_errstr(int);
2b010 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2b020 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 : Prepared State
2b030 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b ment Object.** K
2b040 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 EYWORDS: {prepar
2b050 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 ed statement} {p
2b060 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2b070 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 ts}.**.** An ins
2b080 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
2b090 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 ject represents
2b0a0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 a single SQL sta
2b0b0 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 tement that.** h
2b0c0 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 as been compiled
2b0d0 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 into binary for
2b0e0 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 m and is ready t
2b0f0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a o be evaluated..
2b100 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 **.** Think of e
2b110 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ach SQL statemen
2b120 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20 t as a separate
2b130 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d computer program
2b140 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e . The.** origin
2b150 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 al SQL text is s
2b160 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 ource code. A p
2b170 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2b180 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 t object .** is
2b190 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a the compiled obj
2b1a0 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 ect code. All S
2b1b0 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 QL must be conve
2b1c0 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 rted into a.** p
2b1d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2b1e0 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 t before it can
2b1f0 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 be run..**.** Th
2b200 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 e life-cycle of
2b210 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 a prepared state
2b220 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 ment object usua
2b230 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 lly goes like th
2b240 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a is:.**.** <ol>.*
2b250 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 * <li> Create th
2b260 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
2b270 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e ment object usin
2b280 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
2b290 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 re_v2()]..** <li
2b2a0 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f > Bind values to
2b2b0 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 [parameters] us
2b2c0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
2b2d0 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 bind_*().**
2b2e0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
2b2f0 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c <li> Run the SQL
2b300 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c by calling [sql
2b310 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 ite3_step()] one
2b320 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a or more times..
2b330 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 ** <li> Reset th
2b340 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
2b350 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ment using [sqli
2b360 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 te3_reset()] the
2b370 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 n go back.**
2b380 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f to step 2. Do
2b390 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f this zero or mo
2b3a0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 re times..** <li
2b3b0 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 > Destroy the ob
2b3c0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ject using [sqli
2b3d0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e te3_finalize()].
2b3e0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 .** </ol>.*/.typ
2b3f0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
2b400 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 te3_stmt sqlite3
2b410 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 _stmt;../*.** CA
2b420 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 PI3REF: Run-time
2b430 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f Limits.** METHO
2b440 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
2b450 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 ^(This interfac
2b460 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a e allows the siz
2b470 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e e of various con
2b480 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 structs to be li
2b490 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f mited.** on a co
2b4a0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e nnection by conn
2b4b0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 ection basis. T
2b4c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
2b4d0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 er is the.** [da
2b4e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2b4f0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 n] whose limit i
2b500 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 s to be set or q
2b510 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 ueried. The.**
2b520 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
2b530 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b is one of the [
2b540 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 limit categories
2b550 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a ] that define a.
2b560 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 ** class of cons
2b570 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a tructs to be siz
2b580 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 e limited. The
2b590 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
2b5a0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 is the.** new li
2b5b0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e mit for that con
2b5c0 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 struct.)^.**.**
2b5d0 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 ^If the new limi
2b5e0 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 t is a negative
2b5f0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 number, the limi
2b600 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a t is unchanged..
2b610 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 ** ^(For each li
2b620 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c mit category SQL
2b630 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d ITE_LIMIT_<i>NAM
2b640 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 E</i> there is a
2b650 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 .** [limits | h
2b660 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d ard upper bound]
2b670 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 .** set at compi
2b680 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 le-time by a C p
2b690 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
2b6a0 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d o called.** [lim
2b6b0 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 its | SQLITE_MAX
2b6c0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a _<i>NAME</i>]..*
2b6d0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 * (The "_LIMIT_"
2b6e0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 in the name is
2b6f0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 changed to "_MAX
2b700 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d _".))^.** ^Attem
2b710 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 pts to increase
2b720 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 a limit above it
2b730 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 s hard upper bou
2b740 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 nd are.** silent
2b750 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 ly truncated to
2b760 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 the hard upper b
2b770 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 ound..**.** ^Reg
2b780 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
2b790 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 er or not the li
2b7a0 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c mit was changed,
2b7b0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 the .** [sqlite
2b7c0 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 3_limit()] inter
2b7d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
2b7e0 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 prior value of
2b7f0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 the limit..** ^H
2b800 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 ence, to find th
2b810 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 e current value
2b820 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f of a limit witho
2b830 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a ut changing it,.
2b840 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 ** simply invoke
2b850 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
2b860 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 with the third p
2b870 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 arameter set to
2b880 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 -1..**.** Run-ti
2b890 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e me limits are in
2b8a0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 tended for use i
2b8b0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 n applications t
2b8c0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f hat manage.** bo
2b8d0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 th their own int
2b8e0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 ernal database a
2b8f0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 nd also database
2b900 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 s that are contr
2b910 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 olled.** by untr
2b920 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 usted external s
2b930 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d ources. An exam
2b940 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 ple application
2b950 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 might be a.** we
2b960 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 b browser that h
2b970 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 as its own datab
2b980 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 ases for storing
2b990 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 history and.**
2b9a0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 separate databas
2b9b0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 es controlled by
2b9c0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c JavaScript appl
2b9d0 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 ications downloa
2b9e0 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 ded.** off the I
2b9f0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e nternet. The in
2ba00 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 ternal databases
2ba10 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 can be given th
2ba20 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 e.** large, defa
2ba30 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 ult limits. Dat
2ba40 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 abases managed b
2ba50 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 y external sourc
2ba60 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 es can.** be giv
2ba70 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 en much smaller
2ba80 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 limits designed
2ba90 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e to prevent a den
2baa0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a ial of service.*
2bab0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c * attack. Devel
2bac0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f opers might also
2bad0 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 want to use the
2bae0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
2baf0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 thorizer()].** i
2bb00 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 nterface to furt
2bb10 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 her control untr
2bb20 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 usted SQL. The
2bb30 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 size of the data
2bb40 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 base.** created
2bb50 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 by an untrusted
2bb60 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f script can be co
2bb70 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 ntained using th
2bb80 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 e.** [max_page_c
2bb90 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a ount] [PRAGMA]..
2bba0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 **.** New run-ti
2bbb0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 me limit categor
2bbc0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 ies may be added
2bbd0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
2bbe0 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ses..*/.int sqli
2bbf0 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 te3_limit(sqlite
2bc00 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 3*, int id, int
2bc10 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 newVal);../*.**
2bc20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 CAPI3REF: Run-Ti
2bc30 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 me Limit Categor
2bc40 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ies.** KEYWORDS:
2bc50 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 {limit category
2bc60 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f } {*limit catego
2bc70 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ries}.**.** Thes
2bc80 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 e constants defi
2bc90 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f ne various perfo
2bca0 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a rmance limits.**
2bcb0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 that can be low
2bcc0 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 ered at run-time
2bcd0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
2bce0 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 limit()]..** The
2bcf0 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 synopsis of the
2bd00 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 meanings of the
2bd10 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 various limits
2bd20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a is shown below..
2bd30 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e ** Additional in
2bd40 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 formation is ava
2bd50 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 ilable at [limit
2bd60 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 s | Limits in SQ
2bd70 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c Lite]..**.** <dl
2bd80 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 >.** [[SQLITE_LI
2bd90 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c MIT_LENGTH]] ^(<
2bda0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
2bdb0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c LENGTH</dt>.** <
2bdc0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 dd>The maximum s
2bdd0 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e ize of any strin
2bde0 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 g or BLOB or tab
2bdf0 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 le row, in bytes
2be00 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b .<dd>)^.**.** [[
2be10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c SQLITE_LIMIT_SQL
2be20 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e _LENGTH]] ^(<dt>
2be30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c SQLITE_LIMIT_SQL
2be40 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 _LENGTH</dt>.**
2be50 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
2be60 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c length of an SQL
2be70 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 statement, in b
2be80 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a ytes.</dd>)^.**.
2be90 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
2bea0 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 T_COLUMN]] ^(<dt
2beb0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f >SQLITE_LIMIT_CO
2bec0 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LUMN</dt>.** <dd
2bed0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
2bee0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
2bef0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 n a table defini
2bf00 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a tion or in the.*
2bf10 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 * result set of
2bf20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 a [SELECT] or th
2bf30 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
2bf40 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 of columns in a
2bf50 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e n index.** or in
2bf60 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 an ORDER BY or
2bf70 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e GROUP BY clause.
2bf80 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
2bf90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 SQLITE_LIMIT_EXP
2bfa0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e R_DEPTH]] ^(<dt>
2bfb0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 SQLITE_LIMIT_EXP
2bfc0 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 R_DEPTH</dt>.**
2bfd0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
2bfe0 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 depth of the par
2bff0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 se tree on any e
2c000 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 xpression.</dd>)
2c010 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
2c020 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f _LIMIT_COMPOUND_
2c030 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 SELECT]] ^(<dt>S
2c040 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
2c050 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e OUND_SELECT</dt>
2c060 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
2c070 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 mum number of te
2c080 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e rms in a compoun
2c090 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 d SELECT stateme
2c0a0 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a nt.</dd>)^.**.**
2c0b0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
2c0c0 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e VDBE_OP]] ^(<dt>
2c0d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 SQLITE_LIMIT_VDB
2c0e0 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 E_OP</dt>.** <dd
2c0f0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
2c100 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 ber of instructi
2c110 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c ons in a virtual
2c120 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d machine program
2c130 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c .** used to impl
2c140 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 ement an SQL sta
2c150 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c tement. If [sql
2c160 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2c170 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75 )] or.** the equ
2c180 69 76 61 6c 65 6e 74 20 74 72 69 65 73 20 74 6f ivalent tries to
2c190 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 63 65 20 allocate space
2c1a0 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 for more than th
2c1b0 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a is many opcodes.
2c1c0 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 70 ** in a single p
2c1d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2c1e0 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d t, an SQLITE_NOM
2c1f0 45 4d 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 EM error is retu
2c200 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a rned.</dd>)^.**.
2c210 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
2c220 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d T_FUNCTION_ARG]]
2c230 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
2c240 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 MIT_FUNCTION_ARG
2c250 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
2c260 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
2c270 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 of arguments on
2c280 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e a function.</dd>
2c290 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
2c2a0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 E_LIMIT_ATTACHED
2c2b0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
2c2c0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f LIMIT_ATTACHED</
2c2d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
2c2e0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
2c2f0 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 [ATTACH | attac
2c300 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 hed databases].)
2c310 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 ^</dd>.**.** [[S
2c320 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 QLITE_LIMIT_LIKE
2c330 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d _PATTERN_LENGTH]
2c340 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 ].** ^(<dt>SQLIT
2c350 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 E_LIMIT_LIKE_PAT
2c360 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e TERN_LENGTH</dt>
2c370 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
2c380 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 mum length of th
2c390 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 e pattern argume
2c3a0 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d nt to the [LIKE]
2c3b0 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 or.** [GLOB] op
2c3c0 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a erators.</dd>)^.
2c3d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
2c3e0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 IMIT_VARIABLE_NU
2c3f0 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e MBER]].** ^(<dt>
2c400 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 SQLITE_LIMIT_VAR
2c410 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 IABLE_NUMBER</dt
2c420 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
2c430 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 imum index numbe
2c440 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 r of any [parame
2c450 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 ter] in an SQL s
2c460 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a tatement.)^.**.*
2c470 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
2c480 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d _TRIGGER_DEPTH]]
2c490 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
2c4a0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 MIT_TRIGGER_DEPT
2c4b0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
2c4c0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 e maximum depth
2c4d0 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 of recursion for
2c4e0 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 triggers.</dd>)
2c4f0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
2c500 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 _LIMIT_WORKER_TH
2c510 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 READS]] ^(<dt>SQ
2c520 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 LITE_LIMIT_WORKE
2c530 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a R_THREADS</dt>.*
2c540 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
2c550 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 m number of auxi
2c560 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 liary worker thr
2c570 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 eads that a sing
2c580 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 le.** [prepared
2c590 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 statement] may s
2c5a0 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 tart.</dd>)^.**
2c5b0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </dl>.*/.#define
2c5c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 SQLITE_LIMIT_LE
2c5d0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 NGTH
2c5e0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 0.#defin
2c5f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 e SQLITE_LIMIT_S
2c600 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 QL_LENGTH
2c610 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 1.#defi
2c620 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
2c630 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 COLUMN
2c640 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 2.#def
2c650 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
2c660 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 _EXPR_DEPTH
2c670 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 3.#de
2c680 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
2c690 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 T_COMPOUND_SELEC
2c6a0 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 T 4.#d
2c6b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
2c6c0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 IT_VDBE_OP
2c6d0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 5.#
2c6e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
2c6f0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 MIT_FUNCTION_ARG
2c700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 6.
2c710 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
2c720 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 IMIT_ATTACHED
2c730 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 7
2c740 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2c750 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
2c760 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 RN_LENGTH
2c770 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
2c780 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f _LIMIT_VARIABLE_
2c790 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 NUMBER
2c7a0 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 9.#define SQLIT
2c7b0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f E_LIMIT_TRIGGER_
2c7c0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 DEPTH
2c7d0 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 10.#define SQLI
2c7e0 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f TE_LIMIT_WORKER_
2c7f0 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20 THREADS
2c800 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 11../*.** CAPI
2c810 33 52 45 46 3a 20 50 72 65 70 61 72 65 20 46 6c 3REF: Prepare Fl
2c820 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ags.**.** These
2c830 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 constants define
2c840 20 76 61 72 69 6f 75 73 20 66 6c 61 67 73 20 74 various flags t
2c850 68 61 74 20 63 61 6e 20 62 65 20 70 61 73 73 65 hat can be passe
2c860 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72 65 70 46 d into.** "prepF
2c870 6c 61 67 73 22 20 70 61 72 61 6d 65 74 65 72 20 lags" parameter
2c880 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
2c890 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 61 6e prepare_v3()] an
2c8a0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 d.** [sqlite3_pr
2c8b0 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e epare16_v3()] in
2c8c0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 terfaces..**.**
2c8d0 4e 65 77 20 66 6c 61 67 73 20 6d 61 79 20 62 65 New flags may be
2c8e0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
2c8f0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
2c900 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ite..**.** <dl>.
2c910 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50 ** [[SQLITE_PREP
2c920 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 5d 5d ARE_PERSISTENT]]
2c930 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 ^(<dt>SQLITE_PR
2c940 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 EPARE_PERSISTENT
2c950 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
2c960 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f SQLITE_PREPARE_
2c970 50 45 52 53 49 53 54 45 4e 54 20 66 6c 61 67 20 PERSISTENT flag
2c980 69 73 20 61 20 68 69 6e 74 20 74 6f 20 74 68 65 is a hint to the
2c990 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 0a 2a query planner.*
2c9a0 2a 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 * that the prepa
2c9b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 red statement wi
2c9c0 6c 6c 20 62 65 20 72 65 74 61 69 6e 65 64 20 66 ll be retained f
2c9d0 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d 65 20 61 or a long time a
2c9e0 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72 nd.** probably r
2c9f0 65 75 73 65 64 20 6d 61 6e 79 20 74 69 6d 65 73 eused many times
2ca00 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20 74 68 69 .)^ ^Without thi
2ca10 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69 74 65 33 s flag, [sqlite3
2ca20 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 0a 2a _prepare_v3()].*
2ca30 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 * and [sqlite3_p
2ca40 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 61 repare16_v3()] a
2ca50 73 73 75 6d 65 20 74 68 61 74 20 74 68 65 20 70 ssume that the p
2ca60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2ca70 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65 20 75 73 t will .** be us
2ca80 65 64 20 6a 75 73 74 20 6f 6e 63 65 20 6f 72 20 ed just once or
2ca90 61 74 20 6d 6f 73 74 20 61 20 66 65 77 20 74 69 at most a few ti
2caa0 6d 65 73 20 61 6e 64 20 74 68 65 6e 20 64 65 73 mes and then des
2cab0 74 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 troyed using.**
2cac0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2cad0 65 28 29 5d 20 72 65 6c 61 74 69 76 65 6c 79 20 e()] relatively
2cae0 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72 72 65 6e soon. The curren
2caf0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e t implementation
2cb00 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74 68 69 73 acts.** on this
2cb10 20 68 69 6e 74 20 62 79 20 61 76 6f 69 64 69 6e hint by avoidin
2cb20 67 20 74 68 65 20 75 73 65 20 6f 66 20 5b 6c 6f g the use of [lo
2cb30 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 5d 20 okaside memory]
2cb40 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a 2a 2a 20 so as not to.**
2cb50 64 65 70 6c 65 74 65 20 74 68 65 20 6c 69 6d 69 deplete the limi
2cb60 74 65 64 20 73 74 6f 72 65 20 6f 66 20 6c 6f 6f ted store of loo
2cb70 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 46 kaside memory. F
2cb80 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
2cb90 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 79 20 f.** SQLite may
2cba0 61 63 74 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 act on this hint
2cbb0 20 64 69 66 66 65 72 65 6e 74 6c 79 2e 0a 2a 2a differently..**
2cbc0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45 .** [[SQLITE_PRE
2cbd0 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 5d 5d PARE_NORMALIZE]]
2cbe0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 <dt>SQLITE_PREP
2cbf0 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 3c 2f 64 ARE_NORMALIZE</d
2cc00 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 t>.** <dd>The SQ
2cc10 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 52 LITE_PREPARE_NOR
2cc20 4d 41 4c 49 5a 45 20 66 6c 61 67 20 69 73 20 61 MALIZE flag is a
2cc30 20 6e 6f 2d 6f 70 2e 20 54 68 69 73 20 66 6c 61 no-op. This fla
2cc40 67 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62 65 20 g used.** to be
2cc50 72 65 71 75 69 72 65 64 20 66 6f 72 20 61 6e 79 required for any
2cc60 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2cc70 65 6e 74 20 74 68 61 74 20 77 61 6e 74 65 64 20 ent that wanted
2cc80 74 6f 20 75 73 65 20 74 68 65 0a 2a 2a 20 5b 73 to use the.** [s
2cc90 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 qlite3_normalize
2cca0 64 5f 73 71 6c 28 29 5d 20 69 6e 74 65 72 66 61 d_sql()] interfa
2ccb0 63 65 2e 20 20 48 6f 77 65 76 65 72 2c 20 74 68 ce. However, th
2ccc0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 6f e.** [sqlite3_no
2ccd0 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 29 5d 20 rmalized_sql()]
2cce0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 77 interface is now
2ccf0 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 61 6c available to al
2cd00 6c 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 l.** prepared st
2cd10 61 74 65 6d 65 6e 74 73 2c 20 72 65 67 61 72 64 atements, regard
2cd20 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
2cd30 6f 72 20 6e 6f 74 20 74 68 65 79 20 75 73 65 20 or not they use
2cd40 74 68 69 73 0a 2a 2a 20 66 6c 61 67 2e 0a 2a 2a this.** flag..**
2cd50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45 .** [[SQLITE_PRE
2cd60 50 41 52 45 5f 4e 4f 5f 56 54 41 42 5d 5d 20 3c PARE_NO_VTAB]] <
2cd70 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52 dt>SQLITE_PREPAR
2cd80 45 5f 4e 4f 5f 56 54 41 42 3c 2f 64 74 3e 0a 2a E_NO_VTAB</dt>.*
2cd90 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 * <dd>The SQLITE
2cda0 5f 50 52 45 50 41 52 45 5f 4e 4f 5f 56 54 41 42 _PREPARE_NO_VTAB
2cdb0 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 flag causes the
2cdc0 20 53 51 4c 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a SQL compiler.**
2cdd0 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 20 65 72 to return an er
2cde0 72 6f 72 20 28 65 72 72 6f 72 20 63 6f 64 65 20 ror (error code
2cdf0 53 51 4c 49 54 45 5f 45 52 52 4f 52 29 20 69 66 SQLITE_ERROR) if
2ce00 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 the statement u
2ce10 73 65 73 0a 2a 2a 20 61 6e 79 20 76 69 72 74 75 ses.** any virtu
2ce20 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 20 3c 2f al tables..** </
2ce30 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
2ce40 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 QLITE_PREPARE_PE
2ce50 52 53 49 53 54 45 4e 54 20 20 20 20 20 20 20 20 RSISTENT
2ce60 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69 0x01.#defi
2ce70 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 ne SQLITE_PREPAR
2ce80 45 5f 4e 4f 52 4d 41 4c 49 5a 45 20 20 20 20 20 E_NORMALIZE
2ce90 20 20 20 20 20 20 20 20 20 20 30 78 30 32 0a 23 0x02.#
2cea0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 define SQLITE_PR
2ceb0 45 50 41 52 45 5f 4e 4f 5f 56 54 41 42 20 20 20 EPARE_NO_VTAB
2cec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
2ced0 30 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 04../*.** CAPI3R
2cee0 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e EF: Compiling An
2cef0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a SQL Statement.*
2cf00 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c * KEYWORDS: {SQL
2cf10 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 statement compi
2cf20 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ler}.** METHOD:
2cf30 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 sqlite3.** CONST
2cf40 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f RUCTOR: sqlite3_
2cf50 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 stmt.**.** To ex
2cf60 65 63 75 74 65 20 61 6e 20 53 51 4c 20 73 74 61 ecute an SQL sta
2cf70 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73 74 20 tement, it must
2cf80 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 first be compile
2cf90 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f d into a byte-co
2cfa0 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 de.** program us
2cfb0 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 ing one of these
2cfc0 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72 2c 20 routines. Or,
2cfd0 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 in other words,
2cfe0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a these routines.*
2cff0 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 63 74 6f * are constructo
2d000 72 73 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 rs for the [prep
2d010 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2d020 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 object..**.** Th
2d030 65 20 70 72 65 66 65 72 72 65 64 20 72 6f 75 74 e preferred rout
2d040 69 6e 65 20 74 6f 20 75 73 65 20 69 73 20 5b 73 ine to use is [s
2d050 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2d060 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 2()]. The.** [s
2d070 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
2d080 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6c ] interface is l
2d090 65 67 61 63 79 20 61 6e 64 20 73 68 6f 75 6c 64 egacy and should
2d0a0 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 be avoided..**
2d0b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2d0c0 5f 76 33 28 29 5d 20 68 61 73 20 61 6e 20 65 78 _v3()] has an ex
2d0d0 74 72 61 20 22 70 72 65 70 46 6c 61 67 73 22 20 tra "prepFlags"
2d0e0 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 73 20 75 option that is u
2d0f0 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65 63 69 sed.** for speci
2d100 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a al purposes..**.
2d110 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 ** The use of th
2d120 65 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 e UTF-8 interfac
2d130 65 73 20 69 73 20 70 72 65 66 65 72 72 65 64 2c es is preferred,
2d140 20 61 73 20 53 51 4c 69 74 65 20 63 75 72 72 65 as SQLite curre
2d150 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c ntly.** does all
2d160 20 70 61 72 73 69 6e 67 20 75 73 69 6e 67 20 55 parsing using U
2d170 54 46 2d 38 2e 20 20 54 68 65 20 55 54 46 2d 31 TF-8. The UTF-1
2d180 36 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 6 interfaces are
2d190 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61 73 20 provided.** as
2d1a0 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e 20 20 a convenience.
2d1b0 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 The UTF-16 inter
2d1c0 66 61 63 65 73 20 77 6f 72 6b 20 62 79 20 63 6f faces work by co
2d1d0 6e 76 65 72 74 69 6e 67 20 74 68 65 0a 2a 2a 20 nverting the.**
2d1e0 69 6e 70 75 74 20 74 65 78 74 20 69 6e 74 6f 20 input text into
2d1f0 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e 76 6f UTF-8, then invo
2d200 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 65 73 70 king the corresp
2d210 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 69 6e 74 onding UTF-8 int
2d220 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 erface..**.** Th
2d230 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
2d240 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 , "db", is a [da
2d250 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2d260 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d n] obtained from
2d270 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 a.** prior succ
2d280 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
2d290 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
2d2a0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
2d2b0 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 2()] or.** [sqli
2d2c0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 te3_open16()].
2d2d0 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e The database con
2d2e0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 nection must not
2d2f0 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 have been close
2d300 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 d..**.** The sec
2d310 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a ond argument, "z
2d320 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 Sql", is the sta
2d330 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d tement to be com
2d340 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a piled, encoded.*
2d350 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d * as either UTF-
2d360 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 8 or UTF-16. Th
2d370 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 e sqlite3_prepar
2d380 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 e(), sqlite3_pre
2d390 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e pare_v2(),.** an
2d3a0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
2d3b0 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72 66 e_v3().** interf
2d3c0 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 aces use UTF-8,
2d3d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 and sqlite3_prep
2d3e0 61 72 65 31 36 28 29 2c 20 73 71 6c 69 74 65 33 are16(), sqlite3
2d3f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c _prepare16_v2(),
2d400 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f .** and sqlite3_
2d410 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20 75 prepare16_v3() u
2d420 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a se UTF-16..**.**
2d430 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 ^If the nByte a
2d440 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 rgument is negat
2d450 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 ive, then zSql i
2d460 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 s read up to the
2d470 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 .** first zero t
2d480 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e erminator. ^If n
2d490 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 Byte is positive
2d4a0 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 , then it is the
2d4b0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 .** number of by
2d4c0 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 tes read from zS
2d4d0 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 ql. ^If nByte i
2d4e0 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 s zero, then no
2d4f0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
2d500 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 ement is generat
2d510 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 ed..** If the ca
2d520 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 ller knows that
2d530 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 the supplied str
2d540 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 ing is nul-termi
2d550 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 nated, then.** t
2d560 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 here is a small
2d570 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 performance adva
2d580 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 ntage to passing
2d590 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 an nByte parame
2d5a0 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 ter that.** is t
2d5b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
2d5c0 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 es in the input
2d5d0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 string <i>includ
2d5e0 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e ing</i>.** the n
2d5f0 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a ul-terminator..*
2d600 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 *.** ^If pzTail
2d610 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e is not NULL then
2d620 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 *pzTail is made
2d630 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 to point to the
2d640 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 first byte.** p
2d650 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 ast the end of t
2d660 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 he first SQL sta
2d670 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 tement in zSql.
2d680 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
2d690 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 only.** compile
2d6a0 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d the first statem
2d6b0 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 ent in zSql, so
2d6c0 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 *pzTail is left
2d6d0 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 pointing to.** w
2d6e0 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f hat remains unco
2d6f0 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a mpiled..**.** ^*
2d700 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 ppStmt is left p
2d710 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d ointing to a com
2d720 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 piled [prepared
2d730 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
2d740 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 can be.** execut
2d750 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
2d760 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 3_step()]. ^If
2d770 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f there is an erro
2d780 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 r, *ppStmt is se
2d790 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e t.** to NULL. ^
2d7a0 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 If the input tex
2d7b0 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 t contains no SQ
2d7c0 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 L (if the input
2d7d0 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 is an empty.** s
2d7e0 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 tring or a comme
2d7f0 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 nt) then *ppStmt
2d800 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e is set to NULL.
2d810 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 .** The calling
2d820 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 procedure is res
2d830 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c ponsible for del
2d840 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c eting the compil
2d850 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d ed.** SQL statem
2d860 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ent using [sqlit
2d870 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 e3_finalize()] a
2d880 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 fter it has fini
2d890 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a shed with it..**
2d8a0 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 ppStmt may not
2d8b0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e be NULL..**.** ^
2d8c0 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 On success, the
2d8d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
2d8e0 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 ) family of rout
2d8f0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c ines return [SQL
2d900 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 ITE_OK];.** othe
2d910 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 rwise an [error
2d920 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
2d930 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c d..**.** The sql
2d940 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2d950 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 ), sqlite3_prepa
2d960 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 74 65 33 re_v3(), sqlite3
2d970 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c _prepare16_v2(),
2d980 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f .** and sqlite3_
2d990 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20 69 prepare16_v3() i
2d9a0 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 nterfaces are re
2d9b0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c commended for al
2d9c0 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 0a l new programs..
2d9d0 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 69 6e 74 ** The older int
2d9e0 65 72 66 61 63 65 73 20 28 73 71 6c 69 74 65 33 erfaces (sqlite3
2d9f0 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 _prepare() and s
2da00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2da10 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 74 61 69 ()).** are retai
2da20 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 ned for backward
2da30 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c s compatibility,
2da40 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 but their use i
2da50 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a s discouraged..*
2da60 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 22 20 69 * ^In the "vX" i
2da70 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 nterfaces, the p
2da80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2da90 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 t.** that is ret
2daa0 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 urned (the [sqli
2dab0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 te3_stmt] object
2dac0 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 ) contains a cop
2dad0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 y of the.** orig
2dae0 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 inal SQL text. T
2daf0 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b his causes the [
2db00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2db10 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 interface to.**
2db20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 behave different
2db30 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 ly in three ways
2db40 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 :.**.** <ol>.**
2db50 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 <li>.** ^If the
2db60 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 database schema
2db70 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 changes, instead
2db80 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 of returning [S
2db90 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 QLITE_SCHEMA] as
2dba0 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 it.** always us
2dbb0 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 ed to do, [sqlit
2dbc0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
2dbd0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 automatically re
2dbe0 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a compile the SQL.
2dbf0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 ** statement and
2dc00 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 try to run it a
2dc10 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 gain. As many as
2dc20 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 [SQLITE_MAX_SCH
2dc30 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 EMA_RETRY].** re
2dc40 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 tries will occur
2dc50 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f before sqlite3_
2dc60 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 step() gives up
2dc70 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 and returns an e
2dc80 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a rror..** </li>.*
2dc90 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 *.** <li>.** ^Wh
2dca0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 en an error occu
2dcb0 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 rs, [sqlite3_ste
2dcc0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e p()] will return
2dcd0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 one of the deta
2dce0 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 iled.** [error c
2dcf0 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 odes] or [extend
2dd00 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e ed error codes].
2dd10 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 ^The legacy be
2dd20 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a havior was that.
2dd30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
2dd40 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 ()] would only r
2dd50 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 eturn a generic
2dd60 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 [SQLITE_ERROR] r
2dd70 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e esult code.** an
2dd80 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f d the applicatio
2dd90 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 n would have to
2dda0 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 make a second ca
2ddb0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 ll to [sqlite3_r
2ddc0 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 eset()].** in or
2ddd0 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 der to find the
2dde0 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 underlying cause
2ddf0 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e of the problem.
2de00 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 With the "v2" p
2de10 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 repare.** interf
2de20 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c aces, the underl
2de30 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 ying reason for
2de40 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 the error is ret
2de50 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c urned immediatel
2de60 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a y..** </li>.**.*
2de70 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 * <li>.** ^If th
2de80 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 e specific value
2de90 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d bound to [param
2dea0 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 eter | host para
2deb0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a meter] in the .*
2dec0 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d * WHERE clause m
2ded0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 ight influence t
2dee0 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 he choice of que
2def0 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 ry plan for a st
2df00 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e atement,.** then
2df10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 the statement w
2df20 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 ill be automatic
2df30 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c ally recompiled,
2df40 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 as if there had
2df50 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 been .** a sche
2df60 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 ma change, on th
2df70 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 e first [sqlite
2df80 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 3_step()] call f
2df90 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 ollowing any cha
2dfa0 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 nge.** to the [s
2dfb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2dfc0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 | bindings] of
2dfd0 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d that [parameter]
2dfe0 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 . .** ^The speci
2dff0 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 fic value of WHE
2e000 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d RE-clause [param
2e010 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c eter] might infl
2e020 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 uence the .** ch
2e030 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c oice of query pl
2e040 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 an if the parame
2e050 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d ter is the left-
2e060 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b hand side of a [
2e070 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f LIKE].** or [GLO
2e080 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 B] operator or i
2e090 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
2e0a0 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 is compared to a
2e0b0 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e n indexed column
2e0c0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c .** and the [SQL
2e0d0 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 ITE_ENABLE_STAT3
2e0e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
2e0f0 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 ption is enabled
2e100 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f ..** </li>.** </
2e110 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e 73 71 ol>.**.** <p>^sq
2e120 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 lite3_prepare_v3
2e130 28 29 20 64 69 66 66 65 72 73 20 66 72 6f 6d 20 () differs from
2e140 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2e150 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68 61 76 v2() only in hav
2e160 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74 72 61 ing.** the extra
2e170 20 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d prepFlags param
2e180 65 74 65 72 2c 20 77 68 69 63 68 20 69 73 20 61 eter, which is a
2e190 20 62 69 74 20 61 72 72 61 79 20 63 6f 6e 73 69 bit array consi
2e1a0 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20 6f 72 sting of zero or
2e1b0 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 .** more of the
2e1c0 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f [SQLITE_PREPARE_
2e1d0 50 45 52 53 49 53 54 45 4e 54 7c 53 51 4c 49 54 PERSISTENT|SQLIT
2e1e0 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66 6c 61 E_PREPARE_*] fla
2e1f0 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c gs. ^The.** sql
2e200 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2e210 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b ) interface work
2e220 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 s exactly the sa
2e230 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 me as.** sqlite3
2e240 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20 77 69 _prepare_v3() wi
2e250 74 68 20 61 20 7a 65 72 6f 20 70 72 65 70 46 6c th a zero prepFl
2e260 61 67 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a ags parameter..*
2e270 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 /.int sqlite3_pr
2e280 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 epare(. sqlite3
2e290 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
2e2a0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
2e2b0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
2e2c0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 har *zSql,
2e2d0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
2e2e0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 t, UTF-8 encoded
2e2f0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
2e300 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2e310 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
2e320 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
2e330 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
2e340 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
2e350 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
2e360 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
2e370 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c st char **pzTail
2e380 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
2e390 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
2e3a0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
2e3b0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 /.);.int sqlite3
2e3c0 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 _prepare_v2(. s
2e3d0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
2e3e0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
2e3f0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
2e400 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
2e410 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
2e420 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 atement, UTF-8 e
2e430 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
2e440 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
2e450 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
2e460 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
2e470 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
2e480 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
2e490 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
2e4a0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
2e4b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a . const char **
2e4c0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
2e4d0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
2e4e0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
2e4f0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 zSql */.);.int s
2e500 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2e510 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 3(. sqlite3 *db
2e520 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
2e530 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
2e540 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
2e550 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
2e560 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
2e570 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a TF-8 encoded */.
2e580 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
2e590 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
2e5a0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
2e5b0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
2e5c0 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 . unsigned int
2e5d0 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 prepFlags, /* Ze
2e5e0 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 ro or more SQLIT
2e5f0 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 E_PREPARE_ flags
2e600 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 */. sqlite3_st
2e610 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a mt **ppStmt, /*
2e620 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 OUT: Statement
2e630 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
2e640 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 t char **pzTail
2e650 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e /* OUT: Poin
2e660 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f ter to unused po
2e670 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f rtion of zSql */
2e680 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
2e690 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c prepare16(. sql
2e6a0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
2e6b0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
2e6c0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
2e6d0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 st void *zSql,
2e6e0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
2e6f0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e ement, UTF-16 en
2e700 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
2e710 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
2e720 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
2e730 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
2e740 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
2e750 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
2e760 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
2e770 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
2e780 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 const void **p
2e790 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
2e7a0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
2e7b0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
2e7c0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 Sql */.);.int sq
2e7d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2e7e0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v2(. sqlite3 *d
2e7f0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
2e800 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
2e810 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
2e820 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
2e830 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
2e840 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a UTF-16 encoded *
2e850 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
2e860 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
2e870 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
2e880 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
2e890 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
2e8a0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
2e8b0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
2e8c0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
2e8d0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 void **pzTail
2e8e0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
2e8f0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
2e900 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
2e910 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
2e920 72 65 70 61 72 65 31 36 5f 76 33 28 0a 20 20 73 repare16_v3(. s
2e930 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
2e940 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
2e950 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
2e960 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c onst void *zSql,
2e970 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
2e980 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 atement, UTF-16
2e990 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
2e9a0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
2e9b0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
2e9c0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
2e9d0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e n bytes. */. un
2e9e0 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 signed int prepF
2e9f0 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 lags, /* Zero or
2ea00 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 more SQLITE_PRE
2ea10 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 PARE_ flags */.
2ea20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
2ea30 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
2ea40 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
2ea50 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
2ea60 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f d **pzTail /
2ea70 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
2ea80 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
2ea90 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a of zSql */.);..
2eaa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2eab0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 Retrieving State
2eac0 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 ment SQL.** METH
2ead0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2eae0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2eaf0 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 te3_sql(P) inter
2eb00 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
2eb10 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79 ointer to a copy
2eb20 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a of the UTF-8.**
2eb30 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 SQL text used t
2eb40 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72 o create [prepar
2eb50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 ed statement] P
2eb60 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 if P was.** crea
2eb70 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ted by [sqlite3_
2eb80 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b prepare_v2()], [
2eb90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2eba0 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 v3()],.** [sqlit
2ebb0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
2ebc0 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f )], or [sqlite3_
2ebd0 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e prepare16_v3()].
2ebe0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2ebf0 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 _expanded_sql(P)
2ec00 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2ec10 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
2ec20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e a UTF-8.** strin
2ec30 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 g containing the
2ec40 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65 SQL text of pre
2ec50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
2ec60 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 P with.** [bound
2ec70 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70 parameters] exp
2ec80 61 6e 64 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 anded..** ^The s
2ec90 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 qlite3_normalize
2eca0 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 d_sql(P) interfa
2ecb0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
2ecc0 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a nter to a UTF-8.
2ecd0 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 ** string contai
2ece0 6e 69 6e 67 20 74 68 65 20 6e 6f 72 6d 61 6c 69 ning the normali
2ecf0 7a 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 zed SQL text of
2ed00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2ed10 6e 74 20 50 2e 20 20 54 68 65 0a 2a 2a 20 73 65 nt P. The.** se
2ed20 6d 61 6e 74 69 63 73 20 75 73 65 64 20 74 6f 20 mantics used to
2ed30 6e 6f 72 6d 61 6c 69 7a 65 20 61 20 53 51 4c 20 normalize a SQL
2ed40 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 75 6e statement are un
2ed50 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 73 75 specified and su
2ed60 62 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68 61 6e bject.** to chan
2ed70 67 65 2e 20 20 41 74 20 61 20 6d 69 6e 69 6d 75 ge. At a minimu
2ed80 6d 2c 20 6c 69 74 65 72 61 6c 20 76 61 6c 75 65 m, literal value
2ed90 73 20 77 69 6c 6c 20 62 65 20 72 65 70 6c 61 63 s will be replac
2eda0 65 64 20 77 69 74 68 20 73 75 69 74 61 62 6c 65 ed with suitable
2edb0 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 .** placeholders
2edc0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 ..**.** ^(For ex
2edd0 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72 65 70 ample, if a prep
2ede0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 ared statement i
2edf0 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 s created using
2ee00 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 the SQL.** text
2ee10 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 "SELECT $abc,:xy
2ee20 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61 6d 65 z" and if parame
2ee30 74 65 72 20 24 61 62 63 20 69 73 20 62 6f 75 6e ter $abc is boun
2ee40 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32 33 34 d to integer 234
2ee50 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 5.** and paramet
2ee60 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 er :xyz is unbou
2ee70 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 nd, then sqlite3
2ee80 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 _sql() will retu
2ee90 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e rn.** the origin
2eea0 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 al string, "SELE
2eeb0 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 CT $abc,:xyz" bu
2eec0 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 t sqlite3_expand
2eed0 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c ed_sql().** will
2eee0 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43 54 20 return "SELECT
2eef0 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 2345,NULL".)^.**
2ef00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2ef10 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 _expanded_sql()
2ef20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2ef30 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 s NULL if insuff
2ef40 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a icient memory.**
2ef50 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f is available to
2ef60 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 hold the result
2ef70 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 73 75 , or if the resu
2ef80 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 lt would exceed
2ef90 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d the.** the maxim
2efa0 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 um string length
2efb0 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 determined by t
2efc0 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 he [SQLITE_LIMIT
2efd0 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 _LENGTH]..**.**
2efe0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 ^The [SQLITE_TRA
2eff0 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 CE_SIZE_LIMIT] c
2f000 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
2f010 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69 on limits the si
2f020 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 ze of.** bound p
2f030 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69 arameter expansi
2f040 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 ons. ^The [SQLI
2f050 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 TE_OMIT_TRACE] c
2f060 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f ompile-time.** o
2f070 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73 71 6c ption causes sql
2f080 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 ite3_expanded_sq
2f090 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20 72 65 l() to always re
2f0a0 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a turn NULL..**.**
2f0b0 20 5e 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 ^The strings re
2f0c0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
2f0d0 33 5f 73 71 6c 28 50 29 20 61 6e 64 20 73 71 6c 3_sql(P) and sql
2f0e0 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f ite3_normalized_
2f0f0 73 71 6c 28 50 29 0a 2a 2a 20 61 72 65 20 6d 61 sql(P).** are ma
2f100 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74 65 20 naged by SQLite
2f110 61 6e 64 20 61 72 65 20 61 75 74 6f 6d 61 74 69 and are automati
2f120 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65 6e cally freed when
2f130 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a the prepared.**
2f140 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 statement is fi
2f150 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 nalized..** ^The
2f160 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 string returned
2f170 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61 by sqlite3_expa
2f180 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 nded_sql(P), on
2f190 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a the other hand,.
2f1a0 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 ** is obtained f
2f1b0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
2f1c0 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 loc()] and must
2f1d0 62 65 20 66 72 65 65 20 62 79 20 74 68 65 20 61 be free by the a
2f1e0 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 pplication.** by
2f1f0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b passing it to [
2f200 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e sqlite3_free()].
2f210 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
2f220 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 sqlite3_sql(sqli
2f230 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2f240 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f ;.char *sqlite3_
2f250 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c expanded_sql(sql
2f260 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
2f270 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
2f280 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 qlite3_normalize
2f290 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 d_sql(sqlite3_st
2f2a0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
2f2b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 ** CAPI3REF: Det
2f2c0 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c ermine If An SQL
2f2d0 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 Statement Write
2f2e0 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a s The Database.*
2f2f0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
2f300 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
2f310 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 e sqlite3_stmt_r
2f320 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 eadonly(X) inter
2f330 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 face returns tru
2f340 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a e (non-zero) if.
2f350 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 ** and only if t
2f360 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2f370 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 tement] X makes
2f380 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 no direct change
2f390 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 s to.** the cont
2f3a0 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 ent of the datab
2f3b0 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 ase file..**.**
2f3c0 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 Note that [appli
2f3d0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
2f3e0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 QL functions] or
2f3f0 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 .** [virtual tab
2f400 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 les] might chang
2f410 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 e the database i
2f420 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 ndirectly as a s
2f430 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a ide effect. .**
2f440 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ^(For example,
2f450 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f if an applicatio
2f460 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 n defines a func
2f470 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 tion "eval()" th
2f480 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 at .** calls [sq
2f490 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 lite3_exec()], t
2f4a0 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e hen the followin
2f4b0 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 g SQL statement
2f4c0 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 would.** change
2f4d0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
2f4e0 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 e through side-e
2f4f0 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ffects:.**.** <b
2f500 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
2f510 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 ** SELECT eva
2f520 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 l('DELETE FROM t
2f530 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 1') FROM t2;.**
2f540 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
2f550 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 te>.**.** But be
2f560 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 cause the [SELEC
2f570 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 T] statement doe
2f580 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 s not change the
2f590 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a database file.*
2f5a0 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 * directly, sqli
2f5b0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c te3_stmt_readonl
2f5c0 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 y() would still
2f5d0 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a return true.)^.*
2f5e0 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f *.** ^Transactio
2f5f0 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d n control statem
2f600 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 ents such as [BE
2f610 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 GIN], [COMMIT],
2f620 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b [ROLLBACK],.** [
2f630 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 SAVEPOINT], and
2f640 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 [RELEASE] cause
2f650 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 sqlite3_stmt_rea
2f660 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 donly() to retur
2f670 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 n true,.** since
2f680 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 the statements
2f690 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f themselves do no
2f6a0 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 t actually modif
2f6b0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 y the database b
2f6c0 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 ut.** rather the
2f6d0 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 y control the ti
2f6e0 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 ming of when oth
2f6f0 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f er statements mo
2f700 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 dify the .** dat
2f710 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 abase. ^The [AT
2f720 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 TACH] and [DETAC
2f730 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c H] statements al
2f740 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 so cause.** sqli
2f750 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c te3_stmt_readonl
2f760 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 y() to return tr
2f770 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 ue since, while
2f780 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 those statements
2f790 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 .** change the c
2f7a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 onfiguration of
2f7b0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 a database conne
2f7c0 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e ction, they do n
2f7d0 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e ot make .** chan
2f7e0 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 ges to the conte
2f7f0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 nt of the databa
2f800 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b se files on disk
2f810 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
2f820 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
2f830 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
2f840 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45 rns true for [BE
2f850 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 GIN] since.** [B
2f860 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74 EGIN] merely set
2f870 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73 s internal flags
2f880 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e , but the [BEGIN
2f890 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45 |BEGIN IMMEDIATE
2f8a0 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c ] and.** [BEGIN|
2f8b0 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d BEGIN EXCLUSIVE]
2f8c0 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75 commands do tou
2f8d0 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ch the database
2f8e0 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 and so.** sqlite
2f8f0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
2f900 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 ) returns false
2f910 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e for those comman
2f920 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ds..*/.int sqlit
2f930 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
2f940 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
2f950 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
2f960 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 54 68 PI3REF: Query Th
2f970 65 20 45 58 50 4c 41 49 4e 20 53 65 74 74 69 6e e EXPLAIN Settin
2f980 67 20 46 6f 72 20 41 20 50 72 65 70 61 72 65 64 g For A Prepared
2f990 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 Statement.** ME
2f9a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2f9b0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 mt.**.** ^The sq
2f9c0 6c 69 74 65 33 5f 73 74 6d 74 5f 69 73 65 78 70 lite3_stmt_isexp
2f9d0 6c 61 69 6e 28 53 29 20 69 6e 74 65 72 66 61 63 lain(S) interfac
2f9e0 65 20 72 65 74 75 72 6e 73 20 31 20 69 66 20 74 e returns 1 if t
2f9f0 68 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 he.** prepared s
2fa00 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 61 6e tatement S is an
2fa10 20 45 58 50 4c 41 49 4e 20 73 74 61 74 65 6d 65 EXPLAIN stateme
2fa20 6e 74 2c 20 6f 72 20 32 20 69 66 20 74 68 65 0a nt, or 2 if the.
2fa30 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 ** statement S i
2fa40 73 20 61 6e 20 45 58 50 4c 41 49 4e 20 51 55 45 s an EXPLAIN QUE
2fa50 52 59 20 50 4c 41 4e 2e 0a 2a 2a 20 5e 54 68 65 RY PLAN..** ^The
2fa60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 69 73 sqlite3_stmt_is
2fa70 65 78 70 6c 61 69 6e 28 53 29 20 69 6e 74 65 72 explain(S) inter
2fa80 66 61 63 65 20 72 65 74 75 72 6e 73 20 30 20 69 face returns 0 i
2fa90 66 20 53 20 69 73 0a 2a 2a 20 61 6e 20 6f 72 64 f S is.** an ord
2faa0 69 6e 61 72 79 20 73 74 61 74 65 6d 65 6e 74 20 inary statement
2fab0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 or a NULL pointe
2fac0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 r..*/.int sqlite
2fad0 33 5f 73 74 6d 74 5f 69 73 65 78 70 6c 61 69 6e 3_stmt_isexplain
2fae0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
2faf0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
2fb00 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e PI3REF: Determin
2fb10 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 e If A Prepared
2fb20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 Statement Has Be
2fb30 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 en Reset.** METH
2fb40 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2fb50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2fb60 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 te3_stmt_busy(S)
2fb70 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2fb80 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 ns true (non-zer
2fb90 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 o) if the.** [pr
2fba0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2fbb0 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 ] S has been ste
2fbc0 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e pped at least on
2fbd0 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 ce using .** [sq
2fbe0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 lite3_step(S)] b
2fbf0 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 ut has neither r
2fc00 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e un to completion
2fc10 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 (returned.** [S
2fc20 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d QLITE_DONE] from
2fc30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
2fc40 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 )]) nor.** been
2fc50 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c reset using [sql
2fc60 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 ite3_reset(S)].
2fc70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 ^The sqlite3_st
2fc80 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e mt_busy(S).** in
2fc90 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2fca0 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 false if S is a
2fcb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 NULL pointer. I
2fcc0 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a f S is not a .**
2fcd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e NULL pointer an
2fce0 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 d is not a point
2fcf0 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 er to a valid [p
2fd00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2fd10 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 t].** object, th
2fd20 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
2fd30 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 is undefined and
2fd40 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 probably undesi
2fd50 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 rable..**.** Thi
2fd60 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 s interface can
2fd70 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 be used in combi
2fd80 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f nation [sqlite3_
2fd90 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 next_stmt()].**
2fda0 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 to locate all pr
2fdb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2fdc0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 s associated wit
2fdd0 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a h a database .**
2fde0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
2fdf0 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 are in need of
2fe00 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 being reset. Th
2fe10 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a is can be used,.
2fe20 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ** for example,
2fe30 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f in diagnostic ro
2fe40 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 utines to search
2fe50 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a for prepared .*
2fe60 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 * statements tha
2fe70 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 t are holding a
2fe80 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e transaction open
2fe90 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2fea0 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 _stmt_busy(sqlit
2feb0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
2fec0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 * CAPI3REF: Dyna
2fed0 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 mically Typed Va
2fee0 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 lue Object.** KE
2fef0 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 YWORDS: {protect
2ff00 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
2ff10 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 } {unprotected s
2ff20 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a qlite3_value}.**
2ff30 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 .** SQLite uses
2ff40 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 the sqlite3_valu
2ff50 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 e object to repr
2ff60 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 esent all values
2ff70 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 .** that can be
2ff80 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 stored in a data
2ff90 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 base table. SQLi
2ffa0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 te uses dynamic
2ffb0 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 typing.** for th
2ffc0 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 e values it stor
2ffd0 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f es. ^Values sto
2ffe0 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 red in sqlite3_v
2fff0 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 alue objects.**
30000 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c can be integers,
30010 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
30020 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c values, strings,
30030 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e BLOBs, or NULL.
30040 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 .**.** An sqlite
30050 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 3_value object m
30060 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 ay be either "pr
30070 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 otected" or "unp
30080 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f rotected"..** So
30090 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 me interfaces re
300a0 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 quire a protecte
300b0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
300c0 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 Other interfac
300d0 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 es.** will accep
300e0 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 t either a prote
300f0 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f cted or an unpro
30100 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
30110 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 alue..** Every i
30120 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 nterface that ac
30130 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 cepts sqlite3_va
30140 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 lue arguments sp
30150 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 ecifies.** wheth
30160 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 er or not it req
30170 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 uires a protecte
30180 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
30190 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 The.** [sqlite
301a0 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 3_value_dup()] i
301b0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 nterface can be
301c0 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 used to construc
301d0 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 t a new .** prot
301e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
301f0 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 lue from an unpr
30200 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
30210 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 value..**.** The
30220 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 terms "protecte
30230 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 d" and "unprotec
30240 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 ted" refer to wh
30250 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 ether or not.**
30260 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e a mutex is held.
30270 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 An internal mu
30280 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 tex is held for
30290 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 a protected.** s
302a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
302b0 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 ect but no mutex
302c0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 is held for an
302d0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
302e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
302f0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 ect. If SQLite
30300 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 is compiled to b
30310 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 e single-threade
30320 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 d.** (with [SQLI
30330 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
30340 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 and with [sqlit
30350 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d e3_threadsafe()]
30360 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a returning 0).**
30370 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 or if SQLite is
30380 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 run in one of r
30390 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 educed mutex mod
303a0 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 es .** [SQLITE_C
303b0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
303c0 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 AD] or [SQLITE_C
303d0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
303e0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 D].** then there
303f0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 is no distincti
30400 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 on between prote
30410 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 cted and unprote
30420 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
30430 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e value objects an
30440 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 d they can be us
30450 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 ed interchangeab
30460 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a ly. However,.**
30470 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 for maximum cod
30480 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 e portability it
30490 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
304a0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e that application
304b0 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 s.** still make
304c0 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 the distinction
304d0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 between protecte
304e0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 d and unprotecte
304f0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
30500 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 ue objects even
30510 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c when not strictl
30520 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a y required..**.*
30530 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 * ^The sqlite3_v
30540 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 alue objects tha
30550 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 t are passed as
30560 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 parameters into
30570 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
30580 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 ation of [applic
30590 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
305a0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 L functions] are
305b0 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e protected..** ^
305c0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
305d0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 e object returne
305e0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d by.** [sqlite3
305f0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
30600 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e is unprotected.
30610 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 .** Unprotected
30620 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
30630 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 jects may only b
30640 65 20 75 73 65 64 20 61 73 20 61 72 67 75 6d 65 e used as argume
30650 6e 74 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 nts.** to [sqlit
30660 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
30670 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e )], [sqlite3_bin
30680 64 5f 76 61 6c 75 65 28 29 5d 2c 20 61 6e 64 0a d_value()], and.
30690 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ** [sqlite3_valu
306a0 65 5f 64 75 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 e_dup()]..** The
306b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
306c0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 blob | sqlite3_v
306d0 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d alue_type()] fam
306e0 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 ily of.** interf
306f0 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f aces require pro
30700 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
30710 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f alue objects..*/
30720 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
30730 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71 sqlite3_value sq
30740 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a lite3_value;../*
30750 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 .** CAPI3REF: SQ
30760 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 L Function Conte
30770 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 xt Object.**.**
30780 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 The context in w
30790 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 hich an SQL func
307a0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 tion executes is
307b0 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a stored in an.**
307c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
307d0 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 object. ^A poi
307e0 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 nter to an sqlit
307f0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 e3_context objec
30800 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 t.** is always f
30810 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
30820 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 o [application-d
30830 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
30840 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 ions]..** The ap
30850 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
30860 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 d SQL function i
30870 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
30880 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 ll pass this.**
30890 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 pointer through
308a0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 into calls to [s
308b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
308c0 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 t | sqlite3_resu
308d0 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 lt()],.** [sqlit
308e0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
308f0 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 text()], [sqlite
30900 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 3_user_data()],.
30910 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ** [sqlite3_cont
30920 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d ext_db_handle()]
30930 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 , [sqlite3_get_a
30940 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e uxdata()],.** an
30950 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 d/or [sqlite3_se
30960 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f t_auxdata()]..*/
30970 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
30980 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
30990 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b sqlite3_context;
309a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
309b0 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 : Binding Values
309c0 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 To Prepared Sta
309d0 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f tements.** KEYWO
309e0 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d RDS: {host param
309f0 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 eter} {host para
30a00 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 meters} {host pa
30a10 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a rameter name}.**
30a20 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 KEYWORDS: {SQL
30a30 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 parameter} {SQL
30a40 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 parameters} {par
30a50 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a ameter binding}.
30a60 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
30a70 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 e3_stmt.**.** ^(
30a80 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 In the SQL state
30a90 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 ment text input
30aa0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 to [sqlite3_prep
30ab0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 are_v2()] and it
30ac0 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c s variants,.** l
30ad0 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 iterals may be r
30ae0 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 eplaced by a [pa
30af0 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 rameter] that ma
30b00 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c tches one of fol
30b10 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 lowing.** templa
30b20 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a tes:.**.** <ul>.
30b30 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c ** <li> ?.** <l
30b40 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e i> ?NNN.** <li>
30b50 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 :VVV.** <li>
30b60 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 @VVV.** <li> $V
30b70 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a VV.** </ul>.**.*
30b80 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 * In the templat
30b90 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 es above, NNN re
30ba0 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 presents an inte
30bb0 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 ger literal,.**
30bc0 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e and VVV represen
30bd0 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 ts an alphanumer
30be0 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e ic identifier.)^
30bf0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 ^The values of
30c00 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 these.** parame
30c10 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 ters (also calle
30c20 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 d "host paramete
30c30 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c r names" or "SQL
30c40 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a parameters").**
30c50 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e can be set usin
30c60 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 g the sqlite3_bi
30c70 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
30c80 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a defined here..**
30c90 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
30ca0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 rgument to the s
30cb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
30cc0 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 routines is alwa
30cd0 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 ys.** a pointer
30ce0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
30cf0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 stmt] object ret
30d00 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 urned from.** [s
30d10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
30d20 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 2()] or its vari
30d30 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ants..**.** ^The
30d40 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
30d50 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
30d60 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 the SQL paramet
30d70 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a er to be set..**
30d80 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 ^The leftmost S
30d90 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 QL parameter has
30da0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 an index of 1.
30db0 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 ^When the same
30dc0 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 named.** SQL par
30dd0 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d ameter is used m
30de0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 ore than once, s
30df0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 econd and subseq
30e00 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e uent.** occurren
30e10 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d ces have the sam
30e20 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 e index as the f
30e30 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e irst occurrence.
30e40 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 .** ^The index f
30e50 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 or named paramet
30e60 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 ers can be looke
30e70 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a d up using the.*
30e80 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
30e90 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
30ea0 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 )] API if desire
30eb0 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a d. ^The index.*
30ec0 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 * for "?NNN" par
30ed0 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 ameters is the v
30ee0 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 alue of NNN..**
30ef0 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d ^The NNN value m
30f00 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 ust be between 1
30f10 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 and the [sqlite
30f20 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 3_limit()].** pa
30f30 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f rameter [SQLITE_
30f40 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
30f50 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 UMBER] (default
30f60 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a value: 999)..**.
30f70 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 ** ^The third ar
30f80 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 gument is the va
30f90 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 lue to bind to t
30fa0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a he parameter..**
30fb0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 ^If the third p
30fc0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
30fd0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 te3_bind_text()
30fe0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f or sqlite3_bind_
30ff0 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 text16().** or s
31000 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
31010 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 () is a NULL poi
31020 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f nter then the fo
31030 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a urth parameter.*
31040 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 * is ignored and
31050 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 the end result
31060 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 is the same as s
31070 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c qlite3_bind_null
31080 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 ()..**.** ^(In t
31090 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 hose routines th
310a0 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 at have a fourth
310b0 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 argument, its v
310c0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e alue is the.** n
310d0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
310e0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e n the parameter.
310f0 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 To be clear: t
31100 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a he value is the.
31110 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e ** number of <u>
31120 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 bytes</u> in the
31130 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 value, not the
31140 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
31150 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 ters.)^.** ^If t
31160 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
31170 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ter to sqlite3_b
31180 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 ind_text() or sq
31190 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
311a0 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 6().** is negati
311b0 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e ve, then the len
311c0 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e gth of the strin
311d0 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 g is.** the numb
311e0 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 er of bytes up t
311f0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f o the first zero
31200 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 terminator..**
31210 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
31220 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
31230 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 e3_bind_blob() i
31240 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e s negative, then
31250 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 .** the behavior
31260 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
31270 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 * If a non-negat
31280 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d ive fourth param
31290 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 eter is provided
312a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
312b0 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 _text().** or sq
312c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
312d0 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 6() or sqlite3_b
312e0 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 ind_text64() the
312f0 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 n.** that parame
31300 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 ter must be the
31310 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 byte offset.** w
31320 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 here the NUL ter
31330 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 minator would oc
31340 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 cur assuming the
31350 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c string were NUL
31360 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 .** terminated.
31370 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 If any NUL char
31380 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 acters occur at
31390 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 byte offsets les
313a0 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 s than .** the v
313b0 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 alue of the four
313c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 th parameter the
313d0 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 n the resulting
313e0 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c string value wil
313f0 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 l.** contain emb
31400 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 edded NULs. The
31410 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 result of expre
31420 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 ssions involving
31430 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 strings.** with
31440 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 embedded NULs i
31450 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
31460 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 ** ^The fifth ar
31470 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c gument to the BL
31480 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 OB and string bi
31490 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 nding interfaces
314a0 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 .** is a destruc
314b0 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 tor used to disp
314c0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 ose of the BLOB
314d0 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 or.** string aft
314e0 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 er SQLite has fi
314f0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 nished with it.
31500 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 ^The destructor
31510 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f is called.** to
31520 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 dispose of the
31530 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 BLOB or string e
31540 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 ven if the call
31550 74 6f 20 74 68 65 20 62 69 6e 64 20 41 50 49 20 to the bind API
31560 66 61 69 6c 73 2c 0a 2a 2a 20 65 78 63 65 70 74 fails,.** except
31570 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 the destructor
31580 69 73 20 6e 6f 74 20 63 61 6c 6c 65 64 20 69 66 is not called if
31590 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
315a0 65 74 65 72 20 69 73 20 61 20 4e 55 4c 4c 0a 2a eter is a NULL.*
315b0 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 74 68 65 * pointer or the
315c0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
315d0 72 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a r is negative..*
315e0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 * ^If the fifth
315f0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 argument is.** t
31600 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 he special value
31610 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d [SQLITE_STATIC]
31620 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 , then SQLite as
31630 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a sumes that the.*
31640 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
31650 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 in static, unma
31660 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 naged space and
31670 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
31680 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 be freed..** ^I
31690 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 f the fifth argu
316a0 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c ment has the val
316b0 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 ue [SQLITE_TRANS
316c0 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 IENT], then.** S
316d0 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 QLite makes its
316e0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 own private copy
316f0 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d of the data imm
31700 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 ediately, before
31710 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f .** the sqlite3_
31720 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
31730 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
31740 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d ^The sixth argum
31750 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ent to sqlite3_b
31760 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 ind_text64() mus
31770 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b t be one of.** [
31780 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 SQLITE_UTF8], [S
31790 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 QLITE_UTF16], [S
317a0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 QLITE_UTF16BE],
317b0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 or [SQLITE_UTF16
317c0 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 LE].** to specif
317d0 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f y the encoding o
317e0 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 f the text in th
317f0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
31800 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 r. If.** the si
31810 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 xth argument to
31820 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
31830 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 t64() is not one
31840 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 of the.** allow
31850 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 ed values shown
31860 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 above, or if the
31870 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 text encoding i
31880 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 s different.** f
31890 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 rom the encoding
318a0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
318b0 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 e sixth paramete
318c0 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 r, then the beha
318d0 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 vior.** is undef
318e0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ined..**.** ^The
318f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 sqlite3_bind_ze
31900 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 roblob() routine
31910 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 binds a BLOB of
31920 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a length N that.*
31930 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 * is filled with
31940 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 zeroes. ^A zer
31950 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 oblob uses a fix
31960 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d ed amount of mem
31970 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 ory.** (just an
31980 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 integer to hold
31990 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 its size) while
319a0 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 it is being proc
319b0 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c essed..** Zerobl
319c0 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 obs are intended
319d0 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 to serve as pla
319e0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c ceholders for BL
319f0 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e OBs whose.** con
31a00 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 tent is later wr
31a10 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b itten using.** [
31a20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
31a30 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 n | incremental
31a40 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e BLOB I/O] routin
31a50 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 es..** ^A negati
31a60 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 ve value for the
31a70 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 zeroblob result
31a80 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 s in a zero-leng
31a90 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e th BLOB..**.** ^
31aa0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 The sqlite3_bind
31ab0 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54 _pointer(S,I,P,T
31ac0 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73 ,D) routine caus
31ad0 65 73 20 74 68 65 20 49 2d 74 68 20 70 61 72 61 es the I-th para
31ae0 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 meter in.** [pre
31af0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
31b00 20 53 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51 S to have an SQ
31b10 4c 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c L value of NULL,
31b20 20 62 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a but to also be.
31b30 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
31b40 74 68 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50 th the pointer P
31b50 20 6f 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20 of type T. ^D
31b60 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c is either a NULL
31b70 20 70 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 pointer or.** a
31b80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 pointer to a de
31b90 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f structor functio
31ba0 6e 20 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65 n for P. ^SQLite
31bb0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 will invoke the
31bc0 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44 .** destructor D
31bd0 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 with a single a
31be0 72 67 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65 rgument of P whe
31bf0 6e 20 69 74 20 69 73 20 66 69 6e 69 73 68 65 64 n it is finished
31c00 20 75 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 using.** P. Th
31c10 65 20 54 20 70 61 72 61 6d 65 74 65 72 20 73 68 e T parameter sh
31c20 6f 75 6c 64 20 62 65 20 61 20 73 74 61 74 69 63 ould be a static
31c30 20 73 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61 string, prefera
31c40 62 6c 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20 bly a string.**
31c50 6c 69 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c literal. The sql
31c60 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 ite3_bind_pointe
31c70 72 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70 r() routine is p
31c80 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 art of the.** [p
31c90 6f 69 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69 ointer passing i
31ca0 6e 74 65 72 66 61 63 65 5d 20 61 64 64 65 64 20 nterface] added
31cb0 66 6f 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e for SQLite 3.20.
31cc0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 0..**.** ^If any
31cd0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
31ce0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
31cf0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 s are called wit
31d00 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 h a NULL pointer
31d10 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 .** for the [pre
31d20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
31d30 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 or with a prepa
31d40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f red statement fo
31d50 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 r which.** [sqli
31d60 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
31d70 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 been called more
31d80 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b recently than [
31d90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
31da0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 ,.** then the ca
31db0 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b ll will return [
31dc0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 SQLITE_MISUSE].
31dd0 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f If any sqlite3_
31de0 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 bind_().** routi
31df0 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b ne is passed a [
31e00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
31e10 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 nt] that has bee
31e20 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 n finalized, the
31e30 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e .** result is un
31e40 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 defined and prob
31e50 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a ably harmful..**
31e60 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 .** ^Bindings ar
31e70 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 e not cleared by
31e80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 the [sqlite3_re
31e90 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a set()] routine..
31ea0 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 ** ^Unbound para
31eb0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 meters are inter
31ec0 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a preted as NULL..
31ed0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
31ee0 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e e3_bind_* routin
31ef0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 es return [SQLIT
31f00 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 E_OK] on success
31f10 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 or an.** [error
31f20 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 code] if anythi
31f30 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a ng goes wrong..*
31f40 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 * ^[SQLITE_TOOBI
31f50 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 G] might be retu
31f60 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 rned if the size
31f70 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 of a string or
31f80 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 BLOB.** exceeds
31f90 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 limits imposed b
31fa0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 y [sqlite3_limit
31fb0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ]([SQLITE_LIMIT_
31fc0 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b LENGTH]) or.** [
31fd0 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 SQLITE_MAX_LENGT
31fe0 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f H]..** ^[SQLITE_
31ff0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e RANGE] is return
32000 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 ed if the parame
32010 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 ter.** index is
32020 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e out of range. ^
32030 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 [SQLITE_NOMEM] i
32040 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 s returned if ma
32050 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a lloc() fails..**
32060 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
32070 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
32080 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a meter_count()],.
32090 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
320a0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
320b0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
320c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
320d0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 index()]..*/.int
320e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
320f0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ob(sqlite3_stmt*
32100 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
32110 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 d*, int n, void(
32120 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 *)(void*));.int
32130 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
32140 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 b64(sqlite3_stmt
32150 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f *, int, const vo
32160 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e id*, sqlite3_uin
32170 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 t64,.
32180 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 voi
32190 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e d(*)(void*));.in
321a0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 t sqlite3_bind_d
321b0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 ouble(sqlite3_st
321c0 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 mt*, int, double
321d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
321e0 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f ind_int(sqlite3_
321f0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 stmt*, int, int)
32200 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
32210 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 nd_int64(sqlite3
32220 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c _stmt*, int, sql
32230 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 ite3_int64);.int
32240 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 sqlite3_bind_nu
32250 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ll(sqlite3_stmt*
32260 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 , int);.int sqli
32270 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 te3_bind_text(sq
32280 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c lite3_stmt*,int,
32290 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c const char*,int,
322a0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
322b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
322c0 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 d_text16(sqlite3
322d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
322e0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 st void*, int, v
322f0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
32300 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
32310 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f _text64(sqlite3_
32320 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
32330 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 t char*, sqlite3
32340 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 _uint64,.
32350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
32360 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 void(*)(void*)
32370 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 , unsigned char
32380 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 encoding);.int s
32390 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 qlite3_bind_valu
323a0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
323b0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 int, const sqli
323c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
323d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f sqlite3_bind_po
323e0 69 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 inter(sqlite3_st
323f0 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c mt*, int, void*,
32400 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f 69 const char*,voi
32410 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e d(*)(void*));.in
32420 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a t sqlite3_bind_z
32430 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f eroblob(sqlite3_
32440 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 stmt*, int, int
32450 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f n);.int sqlite3_
32460 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 bind_zeroblob64(
32470 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
32480 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 nt, sqlite3_uint
32490 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 64);../*.** CAPI
324a0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 3REF: Number Of
324b0 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a SQL Parameters.*
324c0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
324d0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
324e0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 is routine can b
324f0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 e used to find t
32500 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 he number of [SQ
32510 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a L parameters].**
32520 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 in a [prepared
32530 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c statement]. SQL
32540 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 parameters are
32550 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a tokens of the.**
32560 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e form "?", "?NNN
32570 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 ", ":AAA", "$AAA
32580 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 ", or "@AAA" tha
32590 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c t serve as.** pl
325a0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 aceholders for v
325b0 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b alues that are [
325c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
325d0 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f b | bound].** to
325e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 the parameters
325f0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e at a later time.
32600 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f .**.** ^(This ro
32610 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 utine actually r
32620 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 eturns the index
32630 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 of the largest
32640 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 (rightmost).** p
32650 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c arameter. For al
32660 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f l forms except ?
32670 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 NNN, this will c
32680 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 orrespond to the
32690 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e .** number of un
326a0 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e ique parameters.
326b0 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 If parameters
326c0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d of the ?NNN form
326d0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 are used,.** th
326e0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 ere may be gaps
326f0 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a in the list.)^.*
32700 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
32710 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
32720 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
32730 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
32740 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
32750 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 me()], and.** [s
32760 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
32770 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
32780 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
32790 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
327a0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
327b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
327c0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 REF: Name Of A H
327d0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a ost Parameter.**
327e0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
327f0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 _stmt.**.** ^The
32800 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 sqlite3_bind_pa
32810 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e rameter_name(P,N
32820 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
32830 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 rns.** the name
32840 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c of the N-th [SQL
32850 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 parameter] in t
32860 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
32870 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 tement] P..** ^(
32880 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f SQL parameters o
32890 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e f the form "?NNN
328a0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 " or ":AAA" or "
328b0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a @AAA" or "$AAA".
328c0 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 ** have a name w
328d0 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 hich is the stri
328e0 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 ng "?NNN" or ":A
328f0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 AA" or "@AAA" or
32900 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 "$AAA".** respe
32910 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f ctively..** In o
32920 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
32930 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 initial ":" or "
32940 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 $" or "@" or "?"
32950 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 .** is included
32960 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e as part of the n
32970 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d ame.)^.** ^Param
32980 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 eters of the for
32990 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 m "?" without a
329a0 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 following intege
329b0 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a r have no name.*
329c0 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 * and are referr
329d0 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 ed to as "namele
329e0 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 ss" or "anonymou
329f0 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a s parameters"..*
32a00 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
32a10 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 host parameter h
32a20 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 as an index of 1
32a30 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e , not 0..**.** ^
32a40 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 If the value N i
32a50 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f s out of range o
32a60 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 r if the N-th pa
32a70 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 rameter is.** na
32a80 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c meless, then NUL
32a90 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 L is returned.
32aa0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 ^The returned st
32ab0 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 ring is.** alway
32ac0 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 s in UTF-8 encod
32ad0 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 ing even if the
32ae0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 named parameter
32af0 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c was.** originall
32b00 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 y specified as U
32b10 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 TF-16 in [sqlite
32b20 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 3_prepare16()],.
32b30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
32b40 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 are16_v2()], or
32b50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
32b60 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 16_v3()]..**.**
32b70 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
32b80 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c e3_bind_blob|sql
32b90 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a ite3_bind()],.**
32ba0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
32bb0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 arameter_count()
32bc0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
32bd0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
32be0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 r_index()]..*/.c
32bf0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
32c00 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
32c10 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 r_name(sqlite3_s
32c20 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a tmt*, int);../*.
32c30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 ** CAPI3REF: Ind
32c40 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 ex Of A Paramete
32c50 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e r With A Given N
32c60 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ame.** METHOD: s
32c70 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
32c80 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e * ^Return the in
32c90 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 dex of an SQL pa
32ca0 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 rameter given it
32cb0 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a s name. ^The.**
32cc0 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 index value ret
32cd0 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c urned is suitabl
32ce0 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 e for use as the
32cf0 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d second.** param
32d00 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
32d10 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
32d20 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 e3_bind()]. ^A
32d30 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 zero.** is retur
32d40 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 ned if no matchi
32d50 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 ng parameter is
32d60 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 found. ^The par
32d70 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d ameter.** name m
32d80 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 ust be given in
32d90 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 UTF-8 even if th
32da0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 e original state
32db0 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 ment.** was prep
32dc0 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 ared from UTF-16
32dd0 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c text using [sql
32de0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
32df0 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 2()] or.** [sqli
32e00 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 te3_prepare16_v3
32e10 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ()]..**.** See a
32e20 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
32e30 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
32e40 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
32e50 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
32e60 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e ter_count()], an
32e70 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
32e80 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
32e90 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c e()]..*/.int sql
32ea0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
32eb0 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 ter_index(sqlite
32ec0 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 3_stmt*, const c
32ed0 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a har *zName);../*
32ee0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
32ef0 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 set All Bindings
32f00 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 On A Prepared S
32f10 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 tatement.** METH
32f20 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
32f30 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 .**.** ^Contrary
32f40 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f to the intuitio
32f50 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 n of many, [sqli
32f60 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 te3_reset()] doe
32f70 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 s not reset.** t
32f80 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 he [sqlite3_bind
32f90 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 _blob | bindings
32fa0 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 ] on a [prepared
32fb0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
32fc0 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e ^Use this routin
32fd0 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 e to reset all h
32fe0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 ost parameters t
32ff0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 o NULL..*/.int s
33000 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e qlite3_clear_bin
33010 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 dings(sqlite3_st
33020 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
33030 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 I3REF: Number Of
33040 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 Columns In A Re
33050 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 sult Set.** METH
33060 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
33070 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 .**.** ^Return t
33080 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
33090 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 umns in the resu
330a0 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 lt set returned
330b0 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 by the.** [prepa
330c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 red statement].
330d0 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ^If this routine
330e0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 returns 0, that
330f0 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b means the .** [
33100 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
33110 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 nt] returns no d
33120 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 ata (for example
33130 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a an [UPDATE])..*
33140 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 * ^However, just
33150 20 62 65 63 61 75 73 65 20 74 68 69 73 20 72 6f because this ro
33160 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 utine returns a
33170 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 positive number
33180 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e does not.** mean
33190 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 that one or mor
331a0 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 e rows of data w
331b0 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e ill be returned.
331c0 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 ^A SELECT stat
331d0 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c ement.** will al
331e0 77 61 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 ways have a posi
331f0 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c tive sqlite3_col
33200 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 umn_count() but
33210 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 depending on the
33220 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 .** WHERE clause
33230 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 constraints and
33240 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 the table conte
33250 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 nt, it might ret
33260 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a urn no rows..**.
33270 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
33280 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
33290 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ()].*/.int sqlit
332a0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 e3_column_count(
332b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
332c0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
332d0 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 I3REF: Column Na
332e0 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 mes In A Result
332f0 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 Set.** METHOD: s
33300 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
33310 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
33320 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d s return the nam
33330 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 e assigned to a
33340 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d particular colum
33350 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 n.** in the resu
33360 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c lt set of a [SEL
33370 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 ECT] statement.
33380 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f ^The sqlite3_co
33390 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 lumn_name().** i
333a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
333b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
333c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
333d0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 UTF-8 string.**
333e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
333f0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 mn_name16() retu
33400 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
33410 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
33420 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 ed.** UTF-16 str
33430 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 ing. ^The first
33440 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
33450 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
33460 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 ement].** that i
33470 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 mplements the [S
33480 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
33490 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . ^The second pa
334a0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
334b0 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e * column number.
334c0 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 ^The leftmost
334d0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 column is number
334e0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 0..**.** ^The r
334f0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 eturned string p
33500 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 ointer is valid
33510 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 until either the
33520 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
33530 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 ment].** is dest
33540 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 royed by [sqlite
33550 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 3_finalize()] or
33560 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 until the state
33570 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 ment is automati
33580 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 cally.** reprepa
33590 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 red by the first
335a0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
335b0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 3_step()] for a
335c0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a particular run.*
335d0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e * or until the n
335e0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 ext call to.** s
335f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
33600 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f me() or sqlite3_
33610 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 column_name16()
33620 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 on the same colu
33630 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 mn..**.** ^If sq
33640 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 lite3_malloc() f
33650 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 ails during the
33660 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 processing of ei
33670 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 ther routine.**
33680 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 (for example dur
33690 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e ing a conversion
336a0 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 from UTF-8 to U
336b0 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a TF-16) then a.**
336c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 NULL pointer is
336d0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
336e0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 ^The name of a
336f0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 result column is
33700 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 the value of th
33710 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f e "AS" clause fo
33720 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e r.** that column
33730 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e , if there is an
33740 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 AS clause. If
33750 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 there is no AS c
33760 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 lause.** then th
33770 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f e name of the co
33780 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 lumn is unspecif
33790 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e ied and may chan
337a0 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 ge from.** one r
337b0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
337c0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f to the next..*/
337d0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
337e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
337f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
33800 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f int N);.const vo
33810 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
33820 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 mn_name16(sqlite
33830 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 3_stmt*, int N);
33840 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
33850 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 : Source Of Data
33860 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 In A Query Resu
33870 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 lt.** METHOD: sq
33880 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
33890 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
338a0 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 provide a means
338b0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 to determine th
338c0 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c e database, tabl
338d0 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 e, and.** table
338e0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 column that is t
338f0 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 he origin of a p
33900 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 articular result
33910 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 column in.** [S
33920 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
33930 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f ..** ^The name o
33940 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f f the database o
33950 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d r table or colum
33960 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 n can be returne
33970 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 d as.** either a
33980 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 UTF-8 or UTF-16
33990 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f string. ^The _
339a0 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e database_ routin
339b0 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 es return.** the
339c0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 database name,
339d0 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 the _table_ rout
339e0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 ines return the
339f0 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a table name, and.
33a00 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 ** the origin_ r
33a10 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
33a20 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a he column name..
33a30 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 ** ^The returned
33a40 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 string is valid
33a50 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 until the [prep
33a60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
33a70 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 is destroyed.**
33a80 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
33a90 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e inalize()] or un
33aa0 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e til the statemen
33ab0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c t is automatical
33ac0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 ly.** reprepared
33ad0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 by the first ca
33ae0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
33af0 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 tep()] for a par
33b00 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f ticular run.** o
33b10 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 r until the same
33b20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
33b30 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 requested.** aga
33b40 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e in in a differen
33b50 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a t encoding..**.*
33b60 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 * ^The names ret
33b70 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 urned are the or
33b80 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 iginal un-aliase
33b90 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a d names of the.*
33ba0 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c * database, tabl
33bb0 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a e, and column..*
33bc0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
33bd0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 argument to thes
33be0 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 e interfaces is
33bf0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
33c00 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 ement]..** ^Thes
33c10 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
33c20 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 rn information a
33c30 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 bout the Nth res
33c40 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 ult column retur
33c50 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 ned by.** the st
33c60 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e atement, where N
33c70 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 is the second f
33c80 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 unction argument
33c90 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d ..** ^The left-m
33ca0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f ost column is co
33cb0 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 lumn 0 for these
33cc0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
33cd0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c ^If the Nth col
33ce0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 umn returned by
33cf0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
33d00 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f an expression o
33d10 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e r.** subquery an
33d20 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d d is not a colum
33d30 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c n value, then al
33d40 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 l of these funct
33d50 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e ions return.** N
33d60 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 ULL. ^These rou
33d70 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 tine might also
33d80 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 return NULL if a
33d90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
33da0 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 on error.** occu
33db0 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c rs. ^Otherwise,
33dc0 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 they return the
33dd0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 name of the att
33de0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 ached database,
33df0 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c table,.** or col
33e00 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 umn that query r
33e10 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 esult column was
33e20 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e extracted from.
33e30 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 .**.** ^As with
33e40 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 all other SQLite
33e50 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f APIs, those who
33e60 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 se names end wit
33e70 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a h "16" return.**
33e80 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 UTF-16 encoded
33e90 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 strings and the
33ea0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 other functions
33eb0 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a return UTF-8..**
33ec0 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 .** ^These APIs
33ed0 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 are only availab
33ee0 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 le if the librar
33ef0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 y was compiled w
33f00 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
33f10 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e TE_ENABLE_COLUMN
33f20 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 _METADATA] C-pre
33f30 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c processor symbol
33f40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f ..**.** If two o
33f50 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 r more threads c
33f60 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 all one or more
33f70 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
33f80 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 s against the sa
33f90 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 me.** prepared s
33fa0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c tatement and col
33fb0 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 umn at the same
33fc0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 time then the re
33fd0 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 sults are.** und
33fe0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 efined..**.** If
33ff0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 two or more thr
34000 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 eads call one or
34010 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 more.** [sqlite
34020 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 3_column_databas
34030 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 e_name | column
34040 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 metadata interfa
34050 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 ces].** for the
34060 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 same [prepared s
34070 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 tatement] and re
34080 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 sult column.** a
34090 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 t the same time
340a0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 then the results
340b0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
340c0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
340d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
340e0 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 tabase_name(sqli
340f0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
34100 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
34110 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
34120 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 ase_name16(sqlit
34130 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 e3_stmt*,int);.c
34140 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
34150 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f e3_column_table_
34160 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
34170 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 t*,int);.const v
34180 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
34190 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 umn_table_name16
341a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
341b0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 nt);.const char
341c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
341d0 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 origin_name(sqli
341e0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
341f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
34200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 te3_column_origi
34210 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 n_name16(sqlite3
34220 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a _stmt*,int);../*
34230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
34240 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 clared Datatype
34250 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c Of A Query Resul
34260 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
34270 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
34280 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 ^(The first para
34290 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 meter is a [prep
342a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
342b0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 .** If this stat
342c0 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 ement is a [SELE
342d0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e CT] statement an
342e0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e d the Nth column
342f0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 of the.** retur
34300 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f ned result set o
34310 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 f that [SELECT]
34320 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d is a table colum
34330 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 n (not an.** exp
34340 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 ression or subqu
34350 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 ery) then the de
34360 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 clared type of t
34370 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 he table.** colu
34380 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 mn is returned.)
34390 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 ^ ^If the Nth c
343a0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 olumn of the res
343b0 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a ult set is an.**
343c0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 expression or s
343d0 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 ubquery, then a
343e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 NULL pointer is
343f0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 returned..** ^Th
34400 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
34410 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d g is always UTF-
34420 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 8 encoded..**.**
34430 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ^(For example,
34440 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 given the databa
34450 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a se schema:.**.**
34460 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 CREATE TABLE t1
34470 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a (c1 VARIANT);.**
34480 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c .** and the foll
34490 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 owing statement
344a0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a to be compiled:.
344b0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 **.** SELECT c1
344c0 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b + 1, c1 FROM t1;
344d0 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 .**.** this rout
344e0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e ine would return
344f0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 the string "VAR
34500 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 IANT" for the se
34510 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 cond result.** c
34520 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e olumn (i==1), an
34530 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 d a NULL pointer
34540 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 for the first r
34550 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d esult column (i=
34560 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 =0).)^.**.** ^SQ
34570 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 Lite uses dynami
34580 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e c run-time typin
34590 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 g. ^So just bec
345a0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a ause a column.**
345b0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 is declared to
345c0 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 contain a partic
345d0 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e ular type does n
345e0 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 ot mean that the
345f0 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 .** data stored
34600 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 in that column i
34610 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 s of the declare
34620 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 d type. SQLite
34630 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 is.** strongly t
34640 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 yped, but the ty
34650 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 ping is dynamic
34660 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 not static. ^Ty
34670 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 pe.** is associa
34680 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 ted with individ
34690 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 ual values, not
346a0 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e with the contain
346b0 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 ers.** used to h
346c0 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 old those values
346d0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 ..*/.const char
346e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
346f0 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 decltype(sqlite3
34700 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
34710 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
34720 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 _column_decltype
34730 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
34740 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ,int);../*.** CA
34750 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 PI3REF: Evaluate
34760 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
34770 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
34780 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
34790 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 After a [prepare
347a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 d statement] has
347b0 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 been prepared u
347c0 73 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b sing any of.** [
347d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
347e0 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f v2()], [sqlite3_
347f0 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b prepare_v3()], [
34800 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
34810 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 6_v2()],.** or [
34820 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
34830 36 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 6_v3()] or one o
34840 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 f the legacy.**
34850 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 interfaces [sqli
34860 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
34870 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
34880 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 re16()], this fu
34890 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 nction.** must b
348a0 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 e called one or
348b0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 more times to ev
348c0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 aluate the state
348d0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ment..**.** The
348e0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 details of the b
348f0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 ehavior of the s
34900 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e qlite3_step() in
34910 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a terface depend.*
34920 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 * on whether the
34930 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 statement was p
34940 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 repared using th
34950 65 20 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74 e newer "vX" int
34960 65 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 erfaces.** [sqli
34970 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 te3_prepare_v3()
34980 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ], [sqlite3_prep
34990 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
349a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 te3_prepare16_v3
349b0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
349c0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
349d0 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 or the older le
349e0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
349f0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 es [sqlite3_prep
34a00 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 are()] and [sqli
34a10 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
34a20 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 . The use of th
34a30 65 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e e.** new "vX" in
34a40 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d terface is recom
34a50 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 mended for new a
34a60 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 pplications but
34a70 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e the legacy.** in
34a80 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e terface will con
34a90 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 tinue to be supp
34aa0 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e orted..**.** ^In
34ab0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
34ac0 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 rface, the retur
34ad0 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 n value will be
34ae0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 either [SQLITE_B
34af0 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 USY],.** [SQLITE
34b00 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f _DONE], [SQLITE_
34b10 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 ROW], [SQLITE_ER
34b20 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 ROR], or [SQLITE
34b30 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 _MISUSE]..** ^Wi
34b40 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 th the "v2" inte
34b50 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 rface, any of th
34b60 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 e other [result
34b70 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 codes] or.** [ex
34b80 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
34b90 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 des] might be re
34ba0 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a turned as well..
34bb0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 **.** ^[SQLITE_B
34bc0 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 USY] means that
34bd0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 the database eng
34be0 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 ine was unable t
34bf0 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a o acquire the.**
34c00 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 database locks
34c10 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 it needs to do i
34c20 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 ts job. ^If the
34c30 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 statement is a
34c40 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f [COMMIT].** or o
34c50 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 ccurs outside of
34c60 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 an explicit tra
34c70 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 nsaction, then y
34c80 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 ou can retry the
34c90 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 .** statement.
34ca0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 If the statement
34cb0 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 is not a [COMMI
34cc0 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 T] and occurs wi
34cd0 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 thin an.** expli
34ce0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 cit transaction
34cf0 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 then you should
34d00 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 rollback the tra
34d10 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a nsaction before.
34d20 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a ** continuing..*
34d30 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f *.** ^[SQLITE_DO
34d40 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 NE] means that t
34d50 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 he statement has
34d60 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 finished execut
34d70 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 ing.** successfu
34d80 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 lly. sqlite3_st
34d90 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 ep() should not
34da0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 be called again
34db0 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a on this virtual.
34dc0 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f ** machine witho
34dd0 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 ut first calling
34de0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
34df0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 )] to reset the
34e00 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 virtual.** machi
34e10 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 ne back to its i
34e20 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a nitial state..**
34e30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 .** ^If the SQL
34e40 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 statement being
34e50 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 executed returns
34e60 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 any data, then
34e70 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 [SQLITE_ROW].**
34e80 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 is returned each
34e90 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 time a new row
34ea0 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 of data is ready
34eb0 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 for processing
34ec0 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 by the.** caller
34ed0 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 . The values may
34ee0 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 be accessed usi
34ef0 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 ng the [column a
34f00 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d ccess functions]
34f10 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 ..** sqlite3_ste
34f20 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 p() is called ag
34f30 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 ain to retrieve
34f40 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 the next row of
34f50 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 data..**.** ^[SQ
34f60 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e LITE_ERROR] mean
34f70 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d s that a run-tim
34f80 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 e error (such as
34f90 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a a constraint.**
34fa0 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 violation) has
34fb0 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 occurred. sqlit
34fc0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 e3_step() should
34fd0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 not be called a
34fe0 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 gain on.** the V
34ff0 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 M. More informat
35000 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 ion may be found
35010 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c by calling [sql
35020 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a ite3_errmsg()]..
35030 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 ** ^With the leg
35040 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 acy interface, a
35050 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 more specific e
35060 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 rror code (for e
35070 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 xample,.** [SQLI
35080 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b TE_INTERRUPT], [
35090 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 SQLITE_SCHEMA],
350a0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d [SQLITE_CORRUPT]
350b0 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a , and so forth).
350c0 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e ** can be obtain
350d0 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 ed by calling [s
350e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
350f0 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 on the.** [prepa
35100 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 red statement].
35110 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e ^In the "v2" in
35120 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 terface,.** the
35130 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 more specific er
35140 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 ror code is retu
35150 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 rned directly by
35160 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e sqlite3_step().
35170 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d .**.** [SQLITE_M
35180 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 ISUSE] means tha
35190 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 t the this routi
351a0 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e ne was called in
351b0 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a appropriately..*
351c0 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 * Perhaps it was
351d0 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 called on a [pr
351e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
351f0 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c ] that has.** al
35200 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 ready been [sqli
35210 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 te3_finalize | f
35220 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 inalized] or on
35230 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 one that had.**
35240 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 previously retur
35250 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f ned [SQLITE_ERRO
35260 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f R] or [SQLITE_DO
35270 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c NE]. Or it coul
35280 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 d.** be the case
35290 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 that the same d
352a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
352b0 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 on is being used
352c0 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f by two or.** mo
352d0 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 re threads at th
352e0 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e e same moment in
352f0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 time..**.** For
35300 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 all versions of
35310 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e SQLite up to an
35320 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e d including 3.6.
35330 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 23.1, a call to.
35340 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
35350 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 t()] was require
35360 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f d after sqlite3_
35370 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 step() returned
35380 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 anything.** othe
35390 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 r than [SQLITE_R
353a0 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 OW] before any s
353b0 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 ubsequent invoca
353c0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 tion of.** sqlit
353d0 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c e3_step(). Fail
353e0 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 ure to reset the
353f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
35400 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 ent using .** [s
35410 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
35420 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 would result in
35430 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 an [SQLITE_MISUS
35440 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a E] return from.*
35450 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
35460 2e 20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 . But after [ve
35470 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 rsion 3.6.23.1]
35480 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e ([dateof:3.6.23.
35490 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 1],.** sqlite3_s
354a0 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 tep() began.** c
354b0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
354c0 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 reset()] automat
354d0 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 ically in this c
354e0 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 ircumstance rath
354f0 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 er.** than retur
35500 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 ning [SQLITE_MIS
35510 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e USE]. This is n
35520 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 ot considered a
35530 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a compatibility.**
35540 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 break because a
35550 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 ny application t
35560 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 hat ever receive
35570 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 s an SQLITE_MISU
35580 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 SE error.** is b
35590 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 roken by definit
355a0 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 ion. The [SQLIT
355b0 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 E_OMIT_AUTORESET
355c0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
355d0 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 ption.** can be
355e0 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 used to restore
355f0 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 the legacy behav
35600 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f ior..**.** <b>Go
35610 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c ofy Interface Al
35620 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 ert:</b> In the
35630 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
35640 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 , the sqlite3_st
35650 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 ep().** API alwa
35660 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e ys returns a gen
35670 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c eric error code,
35680 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c [SQLITE_ERROR],
35690 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a following any.*
356a0 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 * error other th
356b0 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d an [SQLITE_BUSY]
356c0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 and [SQLITE_MIS
356d0 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 USE]. You must
356e0 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 call.** [sqlite3
356f0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 _reset()] or [sq
35700 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
35710 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 ] in order to fi
35720 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a nd one of the.**
35730 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 specific [error
35740 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 codes] that bet
35750 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 ter describes th
35760 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 e error..** We a
35770 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 dmit that this i
35780 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e s a goofy design
35790 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 . The problem h
357a0 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a as been fixed.**
357b0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 with the "v2" i
357c0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f nterface. If yo
357d0 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 u prepare all of
357e0 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d your SQL statem
357f0 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 ents.** using [s
35800 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
35810 33 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 3()] or [sqlite3
35820 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a _prepare_v2()].*
35830 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 * or [sqlite3_pr
35840 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 epare16_v2()] or
35850 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
35860 65 31 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 e16_v3()] instea
35870 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 d.** of the lega
35880 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 cy [sqlite3_prep
35890 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 are()] and [sqli
358a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
358b0 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 interfaces,.**
358c0 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 then the more sp
358d0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f ecific [error co
358e0 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 des] are returne
358f0 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 d directly.** by
35900 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e sqlite3_step().
35910 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 The use of the
35920 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 "vX" interfaces
35930 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e is recommended.
35940 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
35950 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d step(sqlite3_stm
35960 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
35970 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 3REF: Number of
35980 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 columns in a res
35990 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f ult set.** METHO
359a0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
359b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
359c0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 e3_data_count(P)
359d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
359e0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
359f0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a columns in the.
35a00 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f ** current row o
35a10 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
35a20 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 of [prepared st
35a30 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e atement] P..** ^
35a40 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 If prepared stat
35a50 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 ement P does not
35a60 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 have results re
35a70 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a ady to return.**
35a80 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 (via calls to t
35a90 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 he [sqlite3_colu
35aa0 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 mn_int | sqlite3
35ab0 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a _column_*()] of.
35ac0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 ** interfaces) t
35ad0 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 hen sqlite3_data
35ae0 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e _count(P) return
35af0 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s 0..** ^The sql
35b00 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
35b10 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 P) routine also
35b20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 returns 0 if P i
35b30 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
35b40 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
35b50 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 3_data_count(P)
35b60 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
35b70 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 0 if the previou
35b80 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 s call to.** [sq
35b90 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 lite3_step](P) r
35ba0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
35bb0 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c DONE]. ^The sql
35bc0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
35bd0 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 P).** will retur
35be0 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 n non-zero if pr
35bf0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b evious call to [
35c00 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 sqlite3_step](P)
35c10 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 returned.** [SQ
35c20 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 LITE_ROW], excep
35c30 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 t in the case of
35c40 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 the [PRAGMA inc
35c50 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d remental_vacuum]
35c60 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 .** where it alw
35c70 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f ays returns zero
35c80 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 since each step
35c90 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 of that multi-s
35ca0 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 tep.** pragma re
35cb0 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 turns 0 columns
35cc0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 of data..**.** S
35cd0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
35ce0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 3_column_count()
35cf0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
35d00 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 _data_count(sqli
35d10 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
35d20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
35d30 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 F: Fundamental D
35d40 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 atatypes.** KEYW
35d50 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 ORDS: SQLITE_TEX
35d60 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 T.**.** ^(Every
35d70 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 value in SQLite
35d80 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 has one of five
35d90 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 fundamental data
35da0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c types:.**.** <ul
35db0 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 >.** <li> 64-bit
35dc0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a signed integer.
35dd0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 ** <li> 64-bit I
35de0 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 EEE floating poi
35df0 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 nt number.** <li
35e00 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e > string.** <li>
35e10 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 BLOB.** <li> NU
35e20 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a LL.** </ul>)^.**
35e30 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
35e40 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f nts are codes fo
35e50 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 r each of those
35e60 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 types..**.** Not
35e70 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 e that the SQLIT
35e80 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 E_TEXT constant
35e90 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e was also used in
35ea0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
35eb0 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 2.** for a compl
35ec0 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 etely different
35ed0 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 meaning. Softwa
35ee0 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 re that links ag
35ef0 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 ainst both.** SQ
35f00 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 Lite version 2 a
35f10 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f nd SQLite versio
35f20 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 n 3 should use S
35f30 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 QLITE3_TEXT, not
35f40 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e .** SQLITE_TEXT.
35f50 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
35f60 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 TE_INTEGER 1.#d
35f70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f efine SQLITE_FLO
35f80 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 AT 2.#define
35f90 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 SQLITE_BLOB
35fa0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
35fb0 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 _NULL 5.#ifd
35fc0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 ef SQLITE_TEXT.#
35fd0 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 undef SQLITE_TE
35fe0 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e XT.#else.# defin
35ff0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 e SQLITE_TEXT
36000 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 3.#endif.#defi
36010 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 ne SQLITE3_TEXT
36020 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 3../*.** CAP
36030 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 I3REF: Result Va
36040 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 lues From A Quer
36050 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b y.** KEYWORDS: {
36060 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
36070 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 nctions}.** METH
36080 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
36090 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 .**.** <b>Summar
360a0 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b y:</b>.** <block
360b0 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 quote><table bor
360c0 64 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e der=0 cellpaddin
360d0 67 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d g=0 cellspacing=
360e0 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 0>.** <tr><td><b
360f0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
36100 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 blob</b><td>&rar
36110 72 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c r;<td>BLOB resul
36120 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e t.** <tr><td><b>
36130 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
36140 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 ouble</b><td>&ra
36150 72 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75 rr;<td>REAL resu
36160 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 lt.** <tr><td><b
36170 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
36180 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 int</b><td>&rarr
36190 3b 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45 ;<td>32-bit INTE
361a0 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 GER result.** <t
361b0 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 r><td><b>sqlite3
361c0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 _column_int64</b
361d0 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36 ><td>→<td>6
361e0 34 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 4-bit INTEGER re
361f0 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e sult.** <tr><td>
36200 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d <b>sqlite3_colum
36210 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 n_text</b><td>&r
36220 61 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45 arr;<td>UTF-8 TE
36230 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 XT result.** <tr
36240 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f ><td><b>sqlite3_
36250 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 column_text16</b
36260 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 ><td>→<td>U
36270 54 46 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c TF-16 TEXT resul
36280 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e t.** <tr><td><b>
36290 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
362a0 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 alue</b><td>&rar
362b0 72 3b 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74 r;<td>The result
362c0 20 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 as an .** [sqli
362d0 74 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74 te3_value|unprot
362e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
362f0 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 lue] object..**
36300 3c 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 <tr><td> <t
36310 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 d> <td>&nbs
36320 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 p;.** <tr><td><b
36330 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
36340 62 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 bytes</b><td>&ra
36350 72 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61 rr;<td>Size of a
36360 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54 BLOB.** or a UT
36370 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 20 F-8 TEXT result
36380 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e in bytes.** <tr>
36390 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 <td><b>sqlite3_c
363a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62 olumn_bytes16&nb
363b0 73 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a sp; </b>.**
363c0 20 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70 <td>→ 
363d0 3b 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20 ; <td>Size
363e0 6f 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58 of UTF-16.** TEX
363f0 54 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 T in bytes.** <t
36400 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 r><td><b>sqlite3
36410 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e _column_type</b>
36420 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65 <td>→<td>De
36430 66 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70 fault.** datatyp
36440 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a e of the result.
36450 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f ** </table></blo
36460 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c ckquote>.**.** <
36470 62 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a b>Details:</b>.*
36480 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
36490 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f ines return info
364a0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 rmation about a
364b0 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 single column of
364c0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
364d0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 result row of a
364e0 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 query. ^In ever
364f0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 y case the first
36500 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
36510 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ointer.** to the
36520 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
36530 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 ment] that is be
36540 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 ing evaluated (t
36550 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
36560 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 *].** that was r
36570 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 eturned from [sq
36580 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
36590 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 ()] or one of it
365a0 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 s variants).** a
365b0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 nd the second ar
365c0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e gument is the in
365d0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d dex of the colum
365e0 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f n for which info
365f0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c rmation.** shoul
36600 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e d be returned. ^
36610 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c The leftmost col
36620 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c umn of the resul
36630 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e t set has the in
36640 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e dex 0..** ^The n
36650 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
36660 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 in the result c
36670 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 an be determined
36680 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
36690 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 e3_column_count(
366a0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 )]..**.** If the
366b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 SQL statement d
366c0 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c oes not currentl
366d0 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c y point to a val
366e0 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 id row, or if th
366f0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 e.** column inde
36700 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 x is out of rang
36710 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 e, the result is
36720 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 undefined..** T
36730 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 hese routines ma
36740 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 y only be called
36750 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 when the most r
36760 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a ecent call to.**
36770 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
36780 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b ] has returned [
36790 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 SQLITE_ROW] and
367a0 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 neither.** [sqli
367b0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 te3_reset()] nor
367c0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
367d0 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 ze()] have been
367e0 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e called subsequen
367f0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f tly..** If any o
36800 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
36810 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 are called afte
36820 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
36830 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
36840 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
36850 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 r after [sqlite3
36860 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 _step()] has ret
36870 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 urned.** somethi
36880 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 ng other than [S
36890 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 QLITE_ROW], the
368a0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
368b0 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 fined..** If [sq
368c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 lite3_step()] or
368d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
368e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
368f0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 inalize()].** ar
36900 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 e called from a
36910 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
36920 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 while any of th
36930 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ese routines.**
36940 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 are pending, the
36950 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 n the results ar
36960 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a e undefined..**.
36970 2a 2a 20 54 68 65 20 66 69 72 73 74 20 73 69 78 ** The first six
36980 20 69 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c interfaces (_bl
36990 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e ob, _double, _in
369a0 74 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74 t, _int64, _text
369b0 2c 20 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a , and _text16).*
369c0 2a 20 65 61 63 68 20 72 65 74 75 72 6e 20 74 68 * each return th
369d0 65 20 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73 e value of a res
369e0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 ult column in a
369f0 73 70 65 63 69 66 69 63 20 64 61 74 61 20 66 6f specific data fo
36a00 72 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65 rmat. If.** the
36a10 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 result column i
36a20 73 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20 s not initially
36a30 69 6e 20 74 68 65 20 72 65 71 75 65 73 74 65 64 in the requested
36a40 20 66 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61 format (for exa
36a50 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20 mple,.** if the
36a60 71 75 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e query returns an
36a70 20 69 6e 74 65 67 65 72 20 62 75 74 20 74 68 65 integer but the
36a80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
36a90 74 65 78 74 28 29 20 69 6e 74 65 72 66 61 63 65 text() interface
36aa0 0a 2a 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65 .** is used to e
36ab0 78 74 72 61 63 74 20 74 68 65 20 76 61 6c 75 65 xtract the value
36ac0 29 20 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61 ) then an automa
36ad0 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 tic type convers
36ae0 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 ion is performed
36af0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
36b00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
36b10 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
36b20 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 ns the.** [SQLIT
36b30 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 E_INTEGER | data
36b40 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 type code] for t
36b50 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 he initial data
36b60 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 type.** of the r
36b70 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e esult column. ^
36b80 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c The returned val
36b90 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 ue is one of [SQ
36ba0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a LITE_INTEGER],.*
36bb0 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d * [SQLITE_FLOAT]
36bc0 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c , [SQLITE_TEXT],
36bd0 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 [SQLITE_BLOB],
36be0 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d or [SQLITE_NULL]
36bf0 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 ..** The return
36c00 76 61 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33 value of sqlite3
36c10 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63 _column_type() c
36c20 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 an be used to de
36c30 63 69 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66 cide which.** of
36c40 20 74 68 65 20 66 69 72 73 74 20 73 69 78 20 69 the first six i
36c50 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 nterface should
36c60 62 65 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 be used to extra
36c70 63 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 ct the column va
36c80 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 lue..** The valu
36c90 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 e returned by sq
36ca0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
36cb0 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e e() is only mean
36cc0 69 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 ingful if no.**
36cd0 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 automatic type c
36ce0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 onversions have
36cf0 6f 63 63 75 72 72 65 64 20 66 6f 72 20 74 68 65 occurred for the
36d00 20 76 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69 value in questi
36d10 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61 on. .** After a
36d20 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
36d30 2c 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 , the result of
36d40 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f calling sqlite3_
36d50 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a column_type().**
36d60 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74 is undefined, t
36d70 68 6f 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20 hough harmless.
36d80 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 Future.** versi
36d90 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 ons of SQLite ma
36da0 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 y change the beh
36db0 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 avior of sqlite3
36dc0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a _column_type().*
36dd0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 * following a ty
36de0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a pe conversion..*
36df0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 *.** If the resu
36e00 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 lt is a BLOB or
36e10 61 20 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74 a TEXT string, t
36e20 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f hen the sqlite3_
36e30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a column_bytes().*
36e40 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c * or sqlite3_col
36e50 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e umn_bytes16() in
36e60 74 65 72 66 61 63 65 73 20 63 61 6e 20 62 65 20 terfaces can be
36e70 75 73 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e used to determin
36e80 65 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 e the size.** of
36e90 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 that BLOB or st
36ea0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ring..**.** ^If
36eb0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
36ec0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 BLOB or UTF-8 st
36ed0 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 ring then the sq
36ee0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
36ef0 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 es().** routine
36f00 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
36f10 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
36f20 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 hat BLOB or stri
36f30 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 ng..** ^If the r
36f40 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 esult is a UTF-1
36f50 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 6 string, then s
36f60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
36f70 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a tes() converts.*
36f80 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 * the string to
36f90 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 UTF-8 and then r
36fa0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
36fb0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e r of bytes..** ^
36fc0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
36fd0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 a numeric value
36fe0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
36ff0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 lumn_bytes() use
37000 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e s.** [sqlite3_sn
37010 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e printf()] to con
37020 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 vert that value
37030 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e to a UTF-8 strin
37040 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a g and returns.**
37050 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
37060 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 ytes in that str
37070 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
37080 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 result is NULL,
37090 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
370a0 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 umn_bytes() retu
370b0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 rns zero..**.**
370c0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
370d0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
370e0 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 16 string then t
370f0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
37100 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 n_bytes16().** r
37110 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
37120 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
37130 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 es in that BLOB
37140 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 or string..** ^I
37150 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
37160 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 a UTF-8 string,
37170 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
37180 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f umn_bytes16() co
37190 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 nverts.** the st
371a0 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 ring to UTF-16 a
371b0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 nd then returns
371c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
371d0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 tes..** ^If the
371e0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 result is a nume
371f0 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 ric value then s
37200 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
37210 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 tes16() uses.**
37220 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
37230 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 f()] to convert
37240 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 that value to a
37250 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e UTF-16 string an
37260 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 d returns.** the
37270 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
37280 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e in that string.
37290 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
372a0 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e lt is NULL, then
372b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
372c0 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e bytes16() return
372d0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 s zero..**.** ^T
372e0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e he values return
372f0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
37300 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 olumn_bytes()] a
37310 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nd .** [sqlite3_
37320 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
37330 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 ] do not include
37340 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e the zero termin
37350 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 ators at the end
37360 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e .** of the strin
37370 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 g. ^For clarity
37380 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 : the values ret
37390 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c urned by.** [sql
373a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
373b0 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 s()] and [sqlite
373c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
373d0 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 ()] are the numb
373e0 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 er of.** bytes i
373f0 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f n the string, no
37400 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
37410 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a characters..**.*
37420 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 * ^Strings retur
37430 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
37440 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 olumn_text() and
37450 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
37460 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 text16(),.** eve
37470 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c n empty strings,
37480 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f are always zero
37490 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 -terminated. ^T
374a0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c he return.** val
374b0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
374c0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f column_blob() fo
374d0 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 r a zero-length
374e0 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 BLOB is a NULL p
374f0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 ointer..**.** <b
37500 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 >Warning:</b> ^T
37510 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e he object return
37520 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
37530 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 olumn_value()] i
37540 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 s an.** [unprote
37550 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
37560 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 ue] object. In
37570 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 a multithreaded
37580 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 environment,.**
37590 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 an unprotected s
375a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
375b0 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 ect may only be
375c0 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 used safely with
375d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
375e0 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b d_value()] and [
375f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
37600 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 alue()]..** If t
37610 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 he [unprotected
37620 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
37630 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 bject returned b
37640 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f y.** [sqlite3_co
37650 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 lumn_value()] is
37660 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 used in any oth
37670 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e er way, includin
37680 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f g calls.** to ro
37690 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c utines like [sql
376a0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 ite3_value_int()
376b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
376c0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
376d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
376e0 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 bytes()], the be
376f0 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 havior is not th
37700 72 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e readsafe..** Hen
37710 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f ce, the sqlite3_
37720 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69 column_value() i
37730 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e nterface.** is n
37740 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 ormally only use
37750 66 75 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69 ful within the i
37760 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
37770 20 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f .** [applicatio
37780 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
37790 6e 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 nctions] or [vir
377a0 74 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f tual tables], no
377b0 74 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d t within.** top-
377c0 6c 65 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f level applicatio
377d0 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 n code..**.** Th
377e0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 e these routines
377f0 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 may attempt to
37800 63 6f 6e 76 65 72 74 20 74 68 65 20 64 61 74 61 convert the data
37810 74 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 type of the resu
37820 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d lt..** ^For exam
37830 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 ple, if the inte
37840 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 rnal representat
37850 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 ion is FLOAT and
37860 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a a text result.*
37870 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 * is requested,
37880 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
37890 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 f()] is used int
378a0 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f ernally to perfo
378b0 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 rm the.** conver
378c0 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c sion automatical
378d0 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f ly. ^(The follo
378e0 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 wing table detai
378f0 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f ls the conversio
37900 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 ns.** that are a
37910 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 pplied:.**.** <b
37920 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 lockquote>.** <t
37930 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e able border="1">
37940 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 .** <tr><th> Int
37950 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 ernal<br>Type <t
37960 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e h> Requested<br>
37970 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 Type <th> Conve
37980 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e rsion.**.** <tr>
37990 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
379a0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
379b0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a > Result is 0.**
379c0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
379d0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 <td> FLOAT
379e0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
379f0 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 0.0.** <tr><td>
37a00 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 NULL <td>
37a10 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 TEXT <td> Re
37a20 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 sult is a NULL p
37a30 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 ointer.** <tr><t
37a40 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
37a50 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
37a60 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c Result is a NULL
37a70 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e pointer.** <tr>
37a80 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 <td> INTEGER <t
37a90 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
37aa0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 > Convert from i
37ab0 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a nteger to float.
37ac0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 ** <tr><td> INTE
37ad0 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 GER <td> TEXT
37ae0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 <td> ASCII r
37af0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
37b00 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c integer.** <tr><
37b10 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
37b20 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
37b30 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 Same as INTEGER
37b40 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 ->TEXT.** <tr><t
37b50 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
37b60 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
37b70 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 [CAST] to INTEGE
37b80 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 R.** <tr><td> F
37b90 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 LOAT <td> TE
37ba0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 XT <td> ASCII
37bb0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
37bc0 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c e float.** <tr><
37bd0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
37be0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
37bf0 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a [CAST] to BLOB.
37c00 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 ** <tr><td> TEX
37c10 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 T <td> INTEGE
37c20 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 R <td> [CAST]
37c30 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 to INTEGER.** <t
37c40 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
37c50 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
37c60 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 td> [CAST] to RE
37c70 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 AL.** <tr><td>
37c80 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 TEXT <td> B
37c90 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 LOB <td> No c
37ca0 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 hange.** <tr><td
37cb0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 > BLOB <td>
37cc0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b INTEGER <td> [
37cd0 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 CAST] to INTEGER
37ce0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c .** <tr><td> BL
37cf0 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 OB <td> FLOA
37d00 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d T <td> [CAST]
37d10 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e to REAL.** <tr>
37d20 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 <td> BLOB <t
37d30 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 d> TEXT <td
37d40 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 > Add a zero ter
37d50 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 minator if neede
37d60 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a d.** </table>.**
37d70 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e </blockquote>)^
37d80 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
37d90 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 when type conve
37da0 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f rsions occur, po
37db0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 inters returned
37dc0 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c by prior.** call
37dd0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
37de0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 umn_blob(), sqli
37df0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
37e00 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c ), and/or.** sql
37e10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
37e20 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 16() may be inva
37e30 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 lidated..** Type
37e40 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 conversions and
37e50 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 pointer invalid
37e60 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 ations might occ
37e70 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c ur.** in the fol
37e80 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a lowing cases:.**
37e90 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
37ea0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e The initial con
37eb0 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 tent is a BLOB a
37ec0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
37ed0 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 n_text() or.**
37ee0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 sqlite3_colu
37ef0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 mn_text16() is c
37f00 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 alled. A zero-t
37f10 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a erminator might.
37f20 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 ** need to
37f30 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 be added to the
37f40 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 string.</li>.**
37f50 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c <li> The initial
37f60 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d content is UTF-
37f70 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 8 text and sqlit
37f80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
37f90 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 6() or.** s
37fa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
37fb0 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 xt16() is called
37fc0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d . The content m
37fd0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 ust be converted
37fe0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d .** to UTF-
37ff0 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 16.</li>.** <li>
38000 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e The initial con
38010 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 tent is UTF-16 t
38020 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f ext and sqlite3_
38030 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f column_bytes() o
38040 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 r.** sqlite
38050 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
38060 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 is called. The
38070 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 content must be
38080 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 converted.**
38090 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e to UTF-8.</li>
380a0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
380b0 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 ^Conversions bet
380c0 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e ween UTF-16be an
380d0 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 d UTF-16le are a
380e0 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c lways done in pl
380f0 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f ace and do.** no
38100 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 t invalidate a p
38110 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 rior pointer, th
38120 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 ough of course t
38130 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 he content of th
38140 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 e buffer.** that
38150 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 the prior point
38160 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 er references wi
38170 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 ll have been mod
38180 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 ified. Other ki
38190 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 nds.** of conver
381a0 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e sion are done in
381b0 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 place when it i
381c0 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 s possible, but
381d0 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a sometimes they.*
381e0 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 * are not possib
381f0 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 le and in those
38200 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e cases prior poin
38210 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 ters are invalid
38220 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ated..**.** The
38230 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 safest policy is
38240 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 to invoke these
38250 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 routines.** in
38260 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
38270 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a wing ways:.**.**
38280 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 <ul>.** <li>sq
38290 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
382a0 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 t() followed by
382b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
382c0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 ytes()</li>.**
382d0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 <li>sqlite3_colu
382e0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 mn_blob() follow
382f0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
38300 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 lumn_bytes()</li
38310 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
38320 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
38330 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 ) followed by sq
38340 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
38350 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c es16()</li>.** <
38360 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 /ul>.**.** In ot
38370 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 her words, you s
38380 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 hould call sqlit
38390 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
383a0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c ,.** sqlite3_col
383b0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 umn_blob(), or s
383c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
383d0 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 xt16() first to
383e0 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 force the result
383f0 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 .** into the des
38400 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 ired format, the
38410 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 n invoke sqlite3
38420 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
38430 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f or.** sqlite3_co
38440 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 lumn_bytes16() t
38450 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 o find the size
38460 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 of the result.
38470 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 Do not mix calls
38480 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 .** to sqlite3_c
38490 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 olumn_text() or
384a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
384b0 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 lob() with calls
384c0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 to.** sqlite3_c
384d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c olumn_bytes16(),
384e0 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 and do not mix
384f0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
38500 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
38510 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 .** with calls t
38520 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
38530 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 _bytes()..**.**
38540 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 ^The pointers re
38550 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 turned are valid
38560 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f until a type co
38570 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 nversion occurs
38580 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 as.** described
38590 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 above, or until
385a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
385b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 or [sqlite3_res
385c0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c et()] or.** [sql
385d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
385e0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 is called. ^Th
385f0 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 e memory space u
38600 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 sed to hold stri
38610 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 ngs.** and BLOBs
38620 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 is freed automa
38630 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 tically. Do not
38640 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 pass the pointe
38650 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 rs returned.** f
38660 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c rom [sqlite3_col
38670 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 umn_blob()], [sq
38680 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
38690 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a t()], etc. into.
386a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
386b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f ()]..**.** As lo
386c0 6e 67 20 61 73 20 74 68 65 20 69 6e 70 75 74 20 ng as the input
386d0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 63 parameters are c
386e0 6f 72 72 65 63 74 2c 20 74 68 65 73 65 20 72 6f orrect, these ro
386f0 75 74 69 6e 65 73 20 77 69 6c 6c 20 6f 6e 6c 79 utines will only
38700 0a 2a 2a 20 66 61 69 6c 20 69 66 20 61 6e 20 6f .** fail if an o
38710 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 65 72 72 ut-of-memory err
38720 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 or occurs during
38730 20 61 20 66 6f 72 6d 61 74 20 63 6f 6e 76 65 72 a format conver
38740 73 69 6f 6e 2e 0a 2a 2a 20 4f 6e 6c 79 20 74 68 sion..** Only th
38750 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 7