0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35 /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 urce code. In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 al notice, here
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 *.** May you
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 do good and not
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 evil..** May
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65 you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 hers..** May
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79 you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76 ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66 ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20 ile defines the
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74 interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73 client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69 . If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64 on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69 onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41 ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73 PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64 tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63 not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74 ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68 e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66 at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61 ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74 s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74 al". Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 ite. We do not
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67 anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65 but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 inor changes.**
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63 ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 e is derived.**
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 this file. Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66 e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 file makes some
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68 this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73 ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64 art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23 ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48 define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72 .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64 g.h> /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74 ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 */../*.** Make
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 C++..*/.#ifdef
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65 __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20 ../*.** Provide
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20 verride linkage
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20 features of the
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69 interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54 fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72 ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65 QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43 fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54 ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53 DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51 QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65 TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50 def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72 nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20 faces as either
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78 deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 perimental. New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 should not use
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72 deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65 faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 atibility only.
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61 ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74 aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69 d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67 ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61 that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 nd gone back to
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 using simple.**
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 le-Time Library
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70 ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61 .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69 luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 ng literal that
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 rsion in the.**
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77 format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61 here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72 er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64 .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 Y is the minor
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65 nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 cro resolves to
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69 an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59 + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20 , and Z are the
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 same.** numbers
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79 N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20 so.** be larger
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65 than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69 from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68 s derived. Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 er Y will.** be
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20 emented or else
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20 ill be reset to
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65 18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73 source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 been stored in
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 ystem</a>. ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65 D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65 which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20 e.** within its
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 ate and time of
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73 or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 h of the entire
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66 source tree. If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65 the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69 has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73 ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74 ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65 checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73 igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65 h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 LITE_VERSION
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d OURCE_ID "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 un-Time Library
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 TE_SOURCE_ID] C
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f file. ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 s might include
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 atch the macros
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72 , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 ing library and
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65 ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30 ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 ins the text of
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 .** macro. ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ant. The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 tring constants
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 within the DLL.
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c BER]. ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 ite3_sourceid()
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 ant whose value
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20 rocessor macro.
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74 Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73 e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67 py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74 amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61 he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68 racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20 e hash might be
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61 void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 on returns 0 or
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 compile time.
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 ed from the .**
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 (). .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 ined at compile
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e n string. ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 pointer. ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 tion at compile
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 time..**.** See
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69 pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66 returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 and only if.**
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74 tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e t mutexes. When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72 THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 threadsafe. Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 itted. Without
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 the mutexes, it
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 rs a measurable
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 importance, it
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 texes. But for
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 maximum safety,
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61 ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 rsion of SQLite
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 interface only
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 x setting.** of
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 ADSAFE] flag. I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 xes are enabled
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61 r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 nfig()].** with
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54 the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65 IZED]. ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 ead safety, not
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 ting made by.**
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 threadsafe().**
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 is unchanged by
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 le.** KEYWORDS:
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 tion} {database
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20 ite database is
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 3". It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69 lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20 ts destructors.
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 There are many
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 ces (such as.**
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65 three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 ss-platform way
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 es typedefs for
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 sqlite3_uint64
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 te_uint64 types
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 lite3_int64 and
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 36854775808 and
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 5807 inclusive.
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 te_uint64 types
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35 6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 64_TYPE. typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45 ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20 _UINT64_TYPE.
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73 te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20 e . typedef
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69 e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 _). typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 4;. typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e se. typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 # define double
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 3REF: Closing A
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75 3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75 tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65 ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 t..** ^Calls to
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 sqlite3_close()
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53 e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 QLITE_OK] if.**
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66 ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61 ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61 d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 n is associated
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65 ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20 ).** will leave
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 is called with
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 eallocated when
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 ished. The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72 ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 bage collected,
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 der in which.**
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 destructors are
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 B handles], and
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 s associated.**
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 3] object prior
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 t. ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61 n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 p] objects then
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64 TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 andles],.** and
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 stroyed while a
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 atically rolled
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 back..**.** The
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 ust be either a
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 NULL.** pointer
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 or an [sqlite3]
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 btained.** from
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 d deprecated. I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 r historical.**
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ted..*/.typedef
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 apper around.**
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 e statements of
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 ce runs zero or
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 atements passed
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 context of the
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 tion] passed in
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 gument. ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 is invoked for
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 QL statements.
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e k invocation. ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 e3_exec().** is
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 re skipped. ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 3_free()].** on
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73 arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 ssage string is
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 not NULL and no
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 ng the callback
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 subsequent SQL
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 esult. ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d mn. ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 nter for the.**
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 L pointer. ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 exec() callback
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 rictions:.**.**
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 e 1st parameter
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 ).** is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 t not close the
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 tion] specified
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 by.** the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 modify the SQL
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 assed into.**
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a exec(. sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 tabase */. cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 t char *sql,
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 . int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a r**,char**), /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 on */. void *,
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 /. char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 g
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 Result Codes.**
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 QLite functions
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 SQLITE_OK
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 0 /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 RROR 1
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72 /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 TE_INTERNAL
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 2 /* Internal
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 SQLITE_PERM
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 3 /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nied */.#define
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 SQLITE_ABORT
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 4 /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 _BUSY 5
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 TE_LOCKED
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6 /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 7 /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 TE_READONLY
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 8 /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f TERRUPT 9 /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 OERR 10
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 /* Some kind of
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 T 11 /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 e database disk
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 LITE_NOTFOUND
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 12 /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 ITE_FULL
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 13 /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 ITE_CANTOPEN
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 14 /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 COL 15 /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f PTY 16 /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 QLITE_SCHEMA
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 17 /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 SQLITE_TOOBIG
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 18 /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 CONSTRAINT 19
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 _MISUSE 21
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 NOLFS 22
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a H 23 /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 SQLITE_FORMAT
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20 24 /* Not
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 used */.#define
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 SQLITE_RANGE
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 25 /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 te3_bind out of
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 SQLITE_NOTADB
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 26 /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 opened that is
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 QLITE_NOTICE
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 27 /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a NING 28 /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 OW 100
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 ne SQLITE_DONE
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 101 /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 tions}.**.** In
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 eturn one of 30
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 lt codes]. Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 ver, experience
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 any of.** these
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f ned. They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 t provide as.**
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 about problems
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 ight like. In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33 .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72 .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 ()] API. Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 e extended code
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 for.** the most
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 )]..*/.#define S
5170: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53 QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53 ING_COLLSEQ (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31 QLITE_ERROR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
51b0: 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59 LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c LITE_ERROR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
51f0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 ITE_IOERR_READ
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c ITE_IOERR | (1<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
5240: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 EAD (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 TE_IOERR | (2<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 E_IOERR_WRITE
5280: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 E_IOERR | (3<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 _IOERR_FSYNC
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 _IOERR | (4<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
52f0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 IOERR_DIR_FSYNC
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a IOERR | (5<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5330: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 OERR_TRUNCATE
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 OERR | (6<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5370: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 ERR_FSTAT
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5390: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 ERR | (7<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
53b0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 RR_UNLOCK
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
53d0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 RR | (8<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
53f0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 R_RDLOCK
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
5410: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 R | (9<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5430: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5450: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 | (10<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5470: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 _BLOCKED
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5490: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 | (11<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
54b0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 _NOMEM
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
54d0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 | (12<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
54f0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 _ACCESS
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5510: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 | (13<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5530: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f _CHECKRESERVEDLO
5540: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 CK (SQLITE_IOERR
5550: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 | (14<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5570: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 _LOCK
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5590: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 | (15<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
55b0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 _CLOSE
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
55d0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 | (16<<8)).#def
55e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
55f0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 _DIR_CLOSE
5600: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5610: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 | (17<<8)).#def
5620: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5630: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 _SHMOPEN
5640: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5650: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 | (18<<8)).#def
5660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5670: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 _SHMSIZE
5680: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5690: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 | (19<<8)).#def
56a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
56b0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 _SHMLOCK
56c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
56d0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 | (20<<8)).#def
56e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
56f0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 _SHMMAP
5700: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5710: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 | (21<<8)).#def
5720: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5730: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 _SEEK
5740: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5750: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 | (22<<8)).#def
5760: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5770: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 _DELETE_NOENT
5780: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5790: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 | (23<<8)).#def
57a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
57b0: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 _MMAP
57c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
57d0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 | (24<<8)).#def
57e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
57f0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 _GETTEMPPATH
5800: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5810: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 | (25<<8)).#def
5820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5830: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 _CONVPATH
5840: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5850: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 | (26<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5870: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20 _VNODE
5880: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5890: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 | (27<<8)).#def
58a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
58b0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20 _AUTH
58c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
58d0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66 | (28<<8)).#def
58e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
58f0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20 _BEGIN_ATOMIC
5900: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5910: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66 | (29<<8)).#def
5920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5930: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20 _COMMIT_ATOMIC
5940: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5950: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66 | (30<<8)).#def
5960: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5970: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 _ROLLBACK_ATOMIC
5980: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5990: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66 | (31<<8)).#def
59a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 ine SQLITE_LOCKE
59b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 D_SHAREDCACHE
59c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 (SQLITE_LOCKE
59d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 D | (1<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
59f0: 45 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 ED_VTAB
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b (SQLITE_LOCK
5a10: 45 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 ED | (2<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
5a30: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 Y_RECOVERY
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 (SQLITE_BUS
5a50: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 Y | (1<<8)).#
5a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 define SQLITE_BU
5a70: 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 SY_SNAPSHOT
5a80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 (SQLITE_BU
5a90: 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a SY | (2<<8)).
5aa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5ab0: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 ANTOPEN_NOTEMPDI
5ac0: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 R (SQLITE_C
5ad0: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 ANTOPEN | (1<<8)
5ae0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5af0: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 _CANTOPEN_ISDIR
5b00: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5b10: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c _CANTOPEN | (2<<
5b20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5b30: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c TE_CANTOPEN_FULL
5b40: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 PATH (SQLI
5b50: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 TE_CANTOPEN | (3
5b60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5b70: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f LITE_CANTOPEN_CO
5b80: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 NVPATH (SQ
5b90: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 LITE_CANTOPEN |
5ba0: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (4<<8)).#define
5bb0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 SQLITE_CORRUPT_V
5bc0: 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 TAB (
5bd0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c SQLITE_CORRUPT |
5be0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
5bf0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f SQLITE_CORRUPT_
5c00: 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20 20 SEQUENCE
5c10: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 (SQLITE_CORRUPT
5c20: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (2<<8)).#defin
5c30: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
5c40: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 Y_RECOVERY
5c50: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c (SQLITE_READONL
5c60: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 Y | (1<<8)).#def
5c70: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f ine SQLITE_READO
5c80: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 NLY_CANTLOCK
5c90: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f (SQLITE_READO
5ca0: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 NLY | (2<<8)).#d
5cb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
5cc0: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 DONLY_ROLLBACK
5cd0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 (SQLITE_REA
5ce0: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a DONLY | (3<<8)).
5cf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
5d00: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 EADONLY_DBMOVED
5d10: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 (SQLITE_R
5d20: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 EADONLY | (4<<8)
5d30: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5d40: 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e _READONLY_CANTIN
5d50: 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 IT (SQLITE
5d60: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c _READONLY | (5<<
5d70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5d80: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45 TE_READONLY_DIRE
5d90: 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49 CTORY (SQLI
5da0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36 TE_READONLY | (6
5db0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5dc0: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 LITE_ABORT_ROLLB
5dd0: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 ACK (SQ
5de0: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c LITE_ABORT | (2<
5df0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5e00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 ITE_CONSTRAINT_C
5e10: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c HECK (SQL
5e20: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5e30: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
5e40: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
5e50: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 NT_COMMITHOOK
5e60: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
5e70: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 NT | (2<<8)).#de
5e80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
5e90: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 TRAINT_FOREIGNKE
5ea0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 Y (SQLITE_CONS
5eb0: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 TRAINT | (3<<8))
5ec0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5ed0: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 CONSTRAINT_FUNCT
5ee0: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f ION (SQLITE_
5ef0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c CONSTRAINT | (4<
5f00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5f10: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e ITE_CONSTRAINT_N
5f20: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c OTNULL (SQL
5f30: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5f40: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (5<<8)).#define
5f50: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
5f60: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 NT_PRIMARYKEY
5f70: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
5f80: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 NT | (6<<8)).#de
5f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
5fa0: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 TRAINT_TRIGGER
5fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
5fc0: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 TRAINT | (7<<8))
5fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5fe0: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 CONSTRAINT_UNIQU
5ff0: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f E (SQLITE_
6000: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c CONSTRAINT | (8<
6010: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
6020: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 ITE_CONSTRAINT_V
6030: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c TAB (SQL
6040: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
6050: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (9<<8)).#define
6060: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
6070: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 NT_ROWID
6080: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
6090: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 NT |(10<<8)).#de
60a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 fine SQLITE_NOTI
60b0: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 CE_RECOVER_WAL
60c0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 (SQLITE_NOTI
60d0: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 CE | (1<<8)).#de
60e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 fine SQLITE_NOTI
60f0: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 CE_RECOVER_ROLLB
6100: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 ACK (SQLITE_NOTI
6110: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 CE | (2<<8)).#de
6120: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e fine SQLITE_WARN
6130: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 ING_AUTOINDEX
6140: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e (SQLITE_WARN
6150: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 ING | (1<<8)).#d
6160: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 efine SQLITE_AUT
6170: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20 H_USER
6180: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 (SQLITE_AUT
6190: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 H | (1<<8)).#def
61a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f ine SQLITE_OK_LO
61b0: 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 AD_PERMANENTLY
61c0: 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 (SQLITE_OK |
61d0: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 (1<<8))../*.** C
61e0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 API3REF: Flags F
61f0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 or File Open Ope
6200: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 rations.**.** Th
6210: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 ese bit values a
6220: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 re intended for
6230: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 use in the.** 3r
6240: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
6250: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e he [sqlite3_open
6260: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 _v2()] interface
6270: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 and.** in the 4
6280: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
6290: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
62a0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a .xOpen] method..
62b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
62c0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 E_OPEN_READONLY
62d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
62e0: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 01 /* Ok for sq
62f0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
6300: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6310: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
6320: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
6330: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 02 /* Ok for sq
6340: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
6350: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6360: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 E_OPEN_CREATE
6370: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
6380: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 04 /* Ok for sq
6390: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
63a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
63b0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
63c0: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 LOSE 0x000000
63d0: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 08 /* VFS only
63e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
63f0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 E_OPEN_EXCLUSIVE
6400: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
6410: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 10 /* VFS only
6420: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6430: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 E_OPEN_AUTOPROXY
6440: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
6450: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 20 /* VFS only
6460: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6470: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 E_OPEN_URI
6480: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
6490: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 40 /* Ok for sq
64a0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
64b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
64c0: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 E_OPEN_MEMORY
64d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
64e0: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 80 /* Ok for sq
64f0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
6500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6510: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 E_OPEN_MAIN_DB
6520: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 0x000001
6530: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
6540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6550: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 E_OPEN_TEMP_DB
6560: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 0x000002
6570: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
6580: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6590: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 E_OPEN_TRANSIENT
65a0: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 _DB 0x000004
65b0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
65c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
65d0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 E_OPEN_MAIN_JOUR
65e0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 NAL 0x000008
65f0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
6600: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6610: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 E_OPEN_TEMP_JOUR
6620: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 NAL 0x000010
6630: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
6640: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6650: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 E_OPEN_SUBJOURNA
6660: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 L 0x000020
6670: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
6680: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6690: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f E_OPEN_MASTER_JO
66a0: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 URNAL 0x000040
66b0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
66c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
66d0: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 E_OPEN_NOMUTEX
66e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 0x000080
66f0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 00 /* Ok for sq
6700: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
6710: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6720: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
6730: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 0x000100
6740: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 00 /* Ok for sq
6750: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
6760: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6770: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
6780: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 HE 0x000200
6790: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 00 /* Ok for sq
67a0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
67b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
67c0: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 E_OPEN_PRIVATECA
67d0: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 CHE 0x000400
67e0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 00 /* Ok for sq
67f0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
6800: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6810: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 E_OPEN_WAL
6820: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 0x000800
6830: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
6840: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a */../* Reserved:
6850: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6860: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 0x00F00
6870: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 000 */../*.** CA
6880: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 PI3REF: Device C
6890: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a haracteristics.*
68a0: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 *.** The xDevice
68b0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 Characteristics
68c0: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 method of the [s
68d0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
68e0: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 s].** object ret
68f0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 urns an integer
6900: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f which is a vecto
6910: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 r of these.** bi
6920: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 t values express
6930: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 ing I/O characte
6940: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d ristics of the m
6950: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 ass storage.** d
6960: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 evice that holds
6970: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 the file that t
6980: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d he [sqlite3_io_m
6990: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 ethods].** refer
69a0: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 s to..**.** The
69b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
69c0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 MIC property mea
69d0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 ns that all writ
69e0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a es of.** any siz
69f0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 e are atomic. T
6a00: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
6a10: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 ATOMICnnn values
6a20: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 .** mean that wr
6a30: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 ites of blocks t
6a40: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 hat are nnn byte
6a50: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a s in size and.**
6a60: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 are aligned to
6a70: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 an address which
6a80: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d is an integer m
6a90: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e ultiple of.** nn
6aa0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 n are atomic. T
6ab0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
6ac0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 SAFE_APPEND valu
6ad0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 e means.** that
6ae0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 when data is app
6af0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c ended to a file,
6b00: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 the data is app
6b10: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 ended.** first t
6b20: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 hen the size of
6b30: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 the file is exte
6b40: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 nded, never the
6b50: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f other.** way aro
6b60: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 und. The SQLITE
6b70: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
6b80: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 L property means
6b90: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 that.** informa
6ba0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 tion is written
6bb0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 to disk in the s
6bc0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c ame order as cal
6bd0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 ls.** to xWrite(
6be0: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 ). The SQLITE_I
6bf0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f OCAP_POWERSAFE_O
6c00: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 VERWRITE propert
6c10: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 y means that.**
6c20: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c after reboot fol
6c30: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f lowing a crash o
6c40: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 r power loss, th
6c50: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 e only bytes in
6c60: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 a.** file that w
6c70: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 ere written at t
6c80: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c he application l
6c90: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 evel might have
6ca0: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 changed.** and t
6cb0: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 hat adjacent byt
6cc0: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 es, even bytes w
6cd0: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 ithin the same s
6ce0: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 ector are.** gua
6cf0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e ranteed to be un
6d00: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 changed. The SQ
6d10: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c LITE_IOCAP_UNDEL
6d20: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e ETABLE_WHEN_OPEN
6d30: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 .** flag indicat
6d40: 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 es that a file c
6d50: 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 annot be deleted
6d60: 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 when open. The
6d70: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 .** SQLITE_IOCAP
6d80: 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 _IMMUTABLE flag
6d90: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 indicates that t
6da0: 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a he file is on.**
6db0: 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 read-only media
6dc0: 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 and cannot be c
6dd0: 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 hanged even by p
6de0: 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a rocesses with.**
6df0: 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c elevated privil
6e00: 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eges..**.** The
6e10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 SQLITE_IOCAP_BAT
6e20: 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 CH_ATOMIC proper
6e30: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 ty means that th
6e40: 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 e underlying.**
6e50: 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f filesystem suppo
6e60: 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70 rts doing multip
6e70: 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 le write operati
6e80: 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77 ons atomically w
6e90: 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69 hen those.** wri
6ea0: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 te operations ar
6eb0: 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b e bracketed by [
6ec0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 SQLITE_FCNTL_BEG
6ed0: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d IN_ATOMIC_WRITE]
6ee0: 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f and.** [SQLITE_
6ef0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f FCNTL_COMMIT_ATO
6f00: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23 MIC_WRITE]..*/.#
6f10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6f20: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 CAP_ATOMIC
6f30: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6f40: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 00001.#define SQ
6f50: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6f60: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 C512
6f70: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 0x00000002.#de
6f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6f90: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 P_ATOMIC1K
6fa0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6fb0: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 004.#define SQLI
6fc0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 TE_IOCAP_ATOMIC2
6fd0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 K
6fe0: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 0x00000008.#defi
6ff0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
7000: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 ATOMIC4K
7010: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 0x0000001
7020: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
7030: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 _IOCAP_ATOMIC8K
7040: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
7050: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 00000020.#define
7060: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
7070: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 OMIC16K
7080: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 0x00000040.
7090: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
70a0: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 OCAP_ATOMIC32K
70b0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
70c0: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 000080.#define S
70d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
70e0: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 IC64K
70f0: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 0x00000100.#d
7100: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
7110: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 AP_SAFE_APPEND
7120: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
7130: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0200.#define SQL
7140: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e ITE_IOCAP_SEQUEN
7150: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 TIAL
7160: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 0x00000400.#def
7170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
7180: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 _UNDELETABLE_WHE
7190: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 N_OPEN 0x000008
71a0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
71b0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 E_IOCAP_POWERSAF
71c0: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 E_OVERWRITE 0
71d0: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e x00001000.#defin
71e0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 e SQLITE_IOCAP_I
71f0: 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 MMUTABLE
7200: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0x00002000
7210: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7220: 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d IOCAP_BATCH_ATOM
7230: 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78 30 IC 0x0
7240: 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 0004000../*.** C
7250: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f API3REF: File Lo
7260: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a cking Levels.**.
7270: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f ** SQLite uses o
7280: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 ne of these inte
7290: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 ger values as th
72a0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 e second.** argu
72b0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 ment to calls it
72c0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c makes to the xL
72d0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 ock() and xUnloc
72e0: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f k() methods.** o
72f0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f f an [sqlite3_io
7300: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
7310: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
7320: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 ITE_LOCK_NONE
7330: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
7340: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 SQLITE_LOCK_SHA
7350: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 RED 1.#de
7360: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
7370: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 _RESERVED 2
7380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7390: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 LOCK_PENDING
73a0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
73b0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 ITE_LOCK_EXCLUSI
73c0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 VE 4../*.**
73d0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 CAPI3REF: Synchr
73e0: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 onization Type F
73f0: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 lags.**.** When
7400: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 SQLite invokes t
7410: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f he xSync() metho
7420: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 d of an.** [sqli
7430: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
7440: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 object it uses a
7450: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a combination of.
7460: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 ** these integer
7470: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 values as the s
7480: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a econd argument..
7490: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 **.** When the S
74a0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f QLITE_SYNC_DATAO
74b0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 NLY flag is used
74c0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 , it means that
74d0: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 the.** sync oper
74e0: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 ation only needs
74f0: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 to flush data t
7500: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 o mass storage.
7510: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d Inode.** inform
7520: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 ation need not b
7530: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 e flushed. If th
7540: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 e lower four bit
7550: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a s of the flag.**
7560: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 equal SQLITE_SY
7570: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 NC_NORMAL, that
7580: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 means to use nor
7590: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 mal fsync() sema
75a0: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 ntics..** If the
75b0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 lower four bits
75c0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 equal SQLITE_SY
75d0: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 NC_FULL, that me
75e0: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 ans.** to use Ma
75f0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c c OS X style ful
7600: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 lsync instead of
7610: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 fsync()..**.**
7620: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 Do not confuse t
7630: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e he SQLITE_SYNC_N
7640: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 ORMAL and SQLITE
7650: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 _SYNC_FULL flags
7660: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 .** with the [PR
7670: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 AGMA synchronous
7680: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 ]=NORMAL and [PR
7690: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 AGMA synchronous
76a0: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e ]=FULL.** settin
76b0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 gs. The [synchr
76c0: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 onous pragma] de
76d0: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 termines when ca
76e0: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 lls to the.** xS
76f0: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f ync VFS method o
7700: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 ccur and applies
7710: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 uniformly acros
7720: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e s all platforms.
7730: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 .** The SQLITE_S
7740: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 YNC_NORMAL and S
7750: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 QLITE_SYNC_FULL
7760: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 flags determine
7770: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 how.** energetic
7780: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 or rigorous or
7790: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e forceful the syn
77a0: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 c operations are
77b0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b and.** only mak
77c0: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f e a difference o
77d0: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 n Mac OSX for th
77e0: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 e default SQLite
77f0: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 code..** (Third
7800: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 -party VFS imple
7810: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 mentations might
7820: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 also make the d
7830: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 istinction.** be
7840: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e tween SQLITE_SYN
7850: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c C_NORMAL and SQL
7860: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 ITE_SYNC_FULL, b
7870: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 ut among the.**
7880: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
7890: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f s natively suppo
78a0: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 rted by SQLite,
78b0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 only Mac OSX.**
78c0: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 cares about the
78d0: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a difference.).*/.
78e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
78f0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 YNC_NORMAL
7900: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 0x00002.#defin
7910: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 e SQLITE_SYNC_FU
7920: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 LL 0x00
7930: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 003.#define SQLI
7940: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
7950: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 0x00010../
7960: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
7970: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e S Interface Open
7980: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a File Handle.**.
7990: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 ** An [sqlite3_f
79a0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 ile] object repr
79b0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 esents an open f
79c0: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b ile in the .** [
79d0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 sqlite3_vfs | OS
79e0: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 interface layer
79f0: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f ]. Individual O
7a00: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 S interface.** i
7a10: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 mplementations w
7a20: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 ill.** want to s
7a30: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a ubclass this obj
7a40: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 ect by appending
7a50: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c additional fiel
7a60: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 ds.** for their
7a70: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d own use. The pM
7a80: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 ethods entry is
7a90: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
7aa0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d ** [sqlite3_io_m
7ab0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 ethods] object t
7ac0: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 hat defines meth
7ad0: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 ods for performi
7ae0: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 ng.** I/O operat
7af0: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e ions on the open
7b00: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 file..*/.typede
7b10: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
7b20: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 _file sqlite3_fi
7b30: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 le;.struct sqlit
7b40: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 e3_file {. cons
7b50: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 t struct sqlite3
7b60: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 _io_methods *pMe
7b70: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f thods; /* Metho
7b80: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 ds for an open f
7b90: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a ile */.};../*.**
7ba0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e CAPI3REF: OS In
7bb0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 terface File Vir
7bc0: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a tual Methods Obj
7bd0: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 ect.**.** Every
7be0: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 file opened by t
7bf0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
7c00: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f xOpen] method po
7c10: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 pulates an.** [s
7c20: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
7c30: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f ect (or, more co
7c40: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 mmonly, a subcla
7c50: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 ss of the.** [sq
7c60: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
7c70: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 ct) with a point
7c80: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
7c90: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
7ca0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 ..** This object
7cb0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 defines the met
7cc0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 hods used to per
7cd0: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 form various ope
7ce0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e rations.** again
7cf0: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 st the open file
7d00: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
7d10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
7d20: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a e] object..**.**
7d30: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 If the [sqlite3
7d40: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 _vfs.xOpen] meth
7d50: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 od sets the sqli
7d60: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
7d70: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f s element .** to
7d80: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e a non-NULL poin
7d90: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 ter, then the sq
7da0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
7db0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a .xClose method.*
7dc0: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 * may be invoked
7dd0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 even if the [sq
7de0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
7df0: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 reported that i
7e00: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a t failed. The.*
7e10: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 * only way to pr
7e20: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 event a call to
7e30: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 xClose following
7e40: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 a failed [sqlit
7e50: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a e3_vfs.xOpen].**
7e60: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c is for the [sql
7e70: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 ite3_vfs.xOpen]
7e80: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 to set the sqlit
7e90: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 e3_file.pMethods
7ea0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e element.** to N
7eb0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ULL..**.** The f
7ec0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
7ed0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e xSync may be on
7ee0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e e of [SQLITE_SYN
7ef0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 C_NORMAL] or.**
7f00: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c [SQLITE_SYNC_FUL
7f10: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 L]. The first c
7f20: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 hoice is the nor
7f30: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 mal fsync()..**
7f40: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 The second choic
7f50: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 e is a Mac OS X
7f60: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 style fullsync.
7f70: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e The [SQLITE_SYN
7f80: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 C_DATAONLY].** f
7f90: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 lag may be ORed
7fa0: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 in to indicate t
7fb0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 hat only the dat
7fc0: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a a of the file.**
7fd0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f and not its ino
7fe0: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 de needs to be s
7ff0: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ynced..**.** The
8000: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 integer values
8010: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 to xLock() and x
8020: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 Unlock() are one
8030: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c of.** <ul>.** <
8040: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
8050: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 _NONE],.** <li>
8060: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 [SQLITE_LOCK_SHA
8070: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 RED],.** <li> [S
8080: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
8090: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 VED],.** <li> [S
80a0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
80b0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 NG], or.** <li>
80c0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 [SQLITE_LOCK_EXC
80d0: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c LUSIVE]..** </ul
80e0: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 >.** xLock() inc
80f0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e reases the lock.
8100: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 xUnlock() decre
8110: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a ases the lock..*
8120: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 * The xCheckRese
8130: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f rvedLock() metho
8140: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 d checks whether
8150: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f any database co
8160: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 nnection,.** eit
8170: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 her in this proc
8180: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f ess or in some o
8190: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 ther process, is
81a0: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 holding a RESER
81b0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c VED,.** PENDING,
81c0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f or EXCLUSIVE lo
81d0: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 ck on the file.
81e0: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 It returns true
81f0: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f .** if such a lo
8200: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 ck exists and fa
8210: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a lse otherwise..*
8220: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f *.** The xFileCo
8230: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 ntrol() method i
8240: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 s a generic inte
8250: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 rface that allow
8260: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 s custom.** VFS
8270: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
8280: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 to directly cont
8290: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 rol an open file
82a0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
82b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
82c0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 rol()] interface
82d0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f . The second "o
82e0: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 p" argument is a
82f0: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 n.** integer opc
8300: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 ode. The third
8310: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 argument is a ge
8320: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e neric pointer in
8330: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 tended to.** poi
8340: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 nt to a structur
8350: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 e that may conta
8360: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 in arguments or
8370: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 space in which t
8380: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 o.** write retur
8390: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e n values. Poten
83a0: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 tial uses for xF
83b0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 ileControl() mig
83c0: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f ht be.** functio
83d0: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f ns to enable blo
83e0: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 cking locks with
83f0: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 timeouts, to ch
8400: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b ange the.** lock
8410: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f ing strategy (fo
8420: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 r example to use
8430: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 dot-file locks)
8440: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 , to inquire.**
8450: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 about the status
8460: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 of a lock, or t
8470: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f o break stale lo
8480: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 cks. The SQLite
8490: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 .** core reserve
84a0: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 s all opcodes le
84b0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 ss than 100 for
84c0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 its own use..**
84d0: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 A [file control
84e0: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f opcodes | list o
84f0: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 f opcodes] less
8500: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 than 100 is avai
8510: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 lable..** Applic
8520: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 ations that defi
8530: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c ne a custom xFil
8540: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
8550: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 should use opcod
8560: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 es.** greater th
8570: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 an 100 to avoid
8580: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 conflicts. VFS
8590: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
85a0: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e should.** return
85b0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e [SQLITE_NOTFOUN
85c0: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 D] for file cont
85d0: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 rol opcodes that
85e0: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 they do not.**
85f0: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a recognize..**.**
8600: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 The xSectorSize
8610: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e () method return
8620: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a s the sector siz
8630: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 e of the.** devi
8640: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 ce that underlie
8650: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 s the file. The
8660: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 sector size is
8670: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 the.** minimum w
8680: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 rite that can be
8690: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f performed witho
86a0: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a ut disturbing.**
86b0: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 other bytes in
86c0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 the file. The x
86d0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 DeviceCharacteri
86e0: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f stics().** metho
86f0: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 d returns a bit
8700: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e vector describin
8710: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 g behaviors of t
8720: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 he.** underlying
8730: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c device:.**.** <
8740: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ul>.** <li> [SQL
8750: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
8760: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
8770: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 E_IOCAP_ATOMIC51
8780: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 2].** <li> [SQLI
8790: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
87a0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
87b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 TE_IOCAP_ATOMIC2
87c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
87d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 TE_IOCAP_ATOMIC4
87e0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
87f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 TE_IOCAP_ATOMIC8
8800: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
8810: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
8820: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 6K].** <li> [SQL
8830: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
8840: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 32K].** <li> [SQ
8850: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8860: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C64K].** <li> [S
8870: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
8880: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e _APPEND].** <li>
8890: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 [SQLITE_IOCAP_S
88a0: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c EQUENTIAL].** <l
88b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
88c0: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 _UNDELETABLE_WHE
88d0: 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 N_OPEN].** <li>
88e0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f [SQLITE_IOCAP_PO
88f0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 WERSAFE_OVERWRIT
8900: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 E].** <li> [SQLI
8910: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 TE_IOCAP_IMMUTAB
8920: 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c LE].** <li> [SQL
8930: 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f ITE_IOCAP_BATCH_
8940: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e ATOMIC].** </ul>
8950: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
8960: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
8970: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
8980: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
8990: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
89a0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
89b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
89c0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
89d0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
89e0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
89f0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
8a00: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
8a10: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
8a20: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
8a30: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
8a40: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
8a50: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
8a60: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
8a70: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
8a80: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
8a90: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
8aa0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
8ab0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
8ac0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
8ad0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
8ae0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
8af0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
8b00: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
8b10: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
8b20: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
8b30: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
8b40: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
8b50: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
8b60: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
8b70: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
8b80: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a to xWrite()..**
8b90: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 .** If xRead() r
8ba0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f eturns SQLITE_IO
8bb0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 ERR_SHORT_READ i
8bc0: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c t must also fill
8bd0: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 .** in the unrea
8be0: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 d portions of th
8bf0: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 e buffer with ze
8c00: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 ros. A VFS that
8c10: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 .** fails to zer
8c20: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 o-fill short rea
8c30: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f ds might seem to
8c40: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c work. However,
8c50: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a .** failure to z
8c60: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 ero-fill short r
8c70: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 eads will eventu
8c80: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 ally lead to.**
8c90: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 database corrupt
8ca0: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ion..*/.typedef
8cb0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
8cc0: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 o_methods sqlite
8cd0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 3_io_methods;.st
8ce0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
8cf0: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 methods {. int
8d00: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 iVersion;. int
8d10: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 (*xClose)(sqlite
8d20: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 3_file*);. int
8d30: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 (*xRead)(sqlite3
8d40: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 _file*, void*, i
8d50: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 nt iAmt, sqlite3
8d60: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 _int64 iOfst);.
8d70: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 int (*xWrite)(s
8d80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f qlite3_file*, co
8d90: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 nst void*, int i
8da0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 Amt, sqlite3_int
8db0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 64 iOfst);. int
8dc0: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 (*xTruncate)(sq
8dd0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c lite3_file*, sql
8de0: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 ite3_int64 size)
8df0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 ;. int (*xSync)
8e00: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
8e10: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e int flags);. in
8e20: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 t (*xFileSize)(s
8e30: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 qlite3_file*, sq
8e40: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 lite3_int64 *pSi
8e50: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f ze);. int (*xLo
8e60: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
8e70: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 *, int);. int (
8e80: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 *xUnlock)(sqlite
8e90: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 3_file*, int);.
8ea0: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 int (*xCheckRes
8eb0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 ervedLock)(sqlit
8ec0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 e3_file*, int *p
8ed0: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 ResOut);. int (
8ee0: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 *xFileControl)(s
8ef0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
8f00: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 t op, void *pArg
8f10: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 );. int (*xSect
8f20: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f orSize)(sqlite3_
8f30: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
8f40: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 xDeviceCharacter
8f50: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f istics)(sqlite3_
8f60: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 file*);. /* Met
8f70: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 hods above are v
8f80: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e alid for version
8f90: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 1 */. int (*xS
8fa0: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 hmMap)(sqlite3_f
8fb0: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 ile*, int iPg, i
8fc0: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f nt pgsz, int, vo
8fd0: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a id volatile**);.
8fe0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b int (*xShmLock
8ff0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
9000: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 int offset, int
9010: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a n, int flags);.
9020: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 void (*xShmBar
9030: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 rier)(sqlite3_fi
9040: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 le*);. int (*xS
9050: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 hmUnmap)(sqlite3
9060: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 _file*, int dele
9070: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 teFlag);. /* Me
9080: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
9090: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f valid for versio
90a0: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 n 2 */. int (*x
90b0: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 Fetch)(sqlite3_f
90c0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ile*, sqlite3_in
90d0: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 t64 iOfst, int i
90e0: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b Amt, void **pp);
90f0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 . int (*xUnfetc
9100: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a h)(sqlite3_file*
9110: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
9120: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b iOfst, void *p);
9130: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 . /* Methods ab
9140: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f ove are valid fo
9150: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 r version 3 */.
9160: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d /* Additional m
9170: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 ethods may be ad
9180: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
9190: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a leases */.};../*
91a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 .** CAPI3REF: St
91b0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 andard File Cont
91c0: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b rol Opcodes.** K
91d0: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 EYWORDS: {file c
91e0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 ontrol opcodes}
91f0: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 {file control op
9200: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 code}.**.** Thes
9210: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
9220: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 nts are opcodes
9230: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e for the xFileCon
9240: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f trol method.** o
9250: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 f the [sqlite3_i
9260: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
9270: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 t and for the [s
9280: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
9290: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 rol()].** interf
92a0: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ace..**.** <ul>.
92b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
92c0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d FCNTL_LOCKSTATE]
92d0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
92e0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
92f0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
9300: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 for debugging.
9310: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 This.** opcode
9320: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 causes the xFile
9330: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 Control method t
9340: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 o write the curr
9350: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 ent state of.**
9360: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 the lock (one of
9370: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f [SQLITE_LOCK_NO
9380: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 NE], [SQLITE_LOC
9390: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 K_SHARED],.** [S
93a0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
93b0: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f VED], [SQLITE_LO
93c0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 CK_PENDING], or
93d0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 [SQLITE_LOCK_EXC
93e0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f LUSIVE]).** into
93f0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 an integer that
9400: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 the pArg argume
9410: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 nt points to. Th
9420: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a is capability.**
9430: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 is used during
9440: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f testing and is o
9450: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 nly available wh
9460: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 en the SQLITE_TE
9470: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 ST.** compile-ti
9480: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 me option is use
9490: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 d..**.** <li>[[S
94a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 QLITE_FCNTL_SIZE
94b0: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b _HINT]].** The [
94c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a SQLITE_FCNTL_SIZ
94d0: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 E_HINT] opcode i
94e0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 s used by SQLite
94f0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 to give the VFS
9500: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 .** layer a hint
9510: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 of how large th
9520: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
9530: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 will grow to be
9540: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 during the.** cu
9550: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f rrent transactio
9560: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 n. This hint is
9570: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 not guaranteed
9580: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 to be accurate b
9590: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 ut it.** is ofte
95a0: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e n close. The un
95b0: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 derlying VFS mig
95c0: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 ht choose to pre
95d0: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 allocate databas
95e0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 e.** file space
95f0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 based on this hi
9600: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 nt in order to h
9610: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 elp writes to th
9620: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 e database.** fi
9630: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a le run faster..*
9640: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
9650: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 E_FCNTL_CHUNK_SI
9660: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ZE]].** The [SQL
9670: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f ITE_FCNTL_CHUNK_
9680: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 SIZE] opcode is
9690: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 used to request
96a0: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 that the VFS.**
96b0: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e extends and trun
96c0: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 cates the databa
96d0: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b se file in chunk
96e0: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 s of a size spec
96f0: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 ified.** by the
9700: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 user. The fourth
9710: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 argument to [sq
9720: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
9730: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a ol()] should .**
9740: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 point to an int
9750: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 eger (type int)
9760: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e containing the n
9770: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f ew chunk-size to
9780: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 use.** for the
9790: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 nominated databa
97a0: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 se. Allocating d
97b0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 atabase file spa
97c0: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 ce in large.** c
97d0: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 hunks (say 1MB a
97e0: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 t a time), may r
97f0: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 educe file-syste
9800: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 m fragmentation
9810: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 and.** improve p
9820: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f erformance on so
9830: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a me systems..**.*
9840: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
9850: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 CNTL_FILE_POINTE
9860: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 R]].** The [SQLI
9870: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f TE_FCNTL_FILE_PO
9880: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 INTER] opcode is
9890: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 used to obtain
98a0: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 a pointer.** to
98b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
98c0: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 e] object associ
98d0: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 ated with a part
98e0: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a icular database.
98f0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 ** connection.
9900: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 See also [SQLITE
9910: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 _FCNTL_JOURNAL_P
9920: 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c OINTER]..**.** <
9930: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
9940: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 L_JOURNAL_POINTE
9950: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 R]].** The [SQLI
9960: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c TE_FCNTL_JOURNAL
9970: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 _POINTER] opcode
9980: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 is used to obta
9990: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 in a pointer.**
99a0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
99b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 file] object ass
99c0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
99d0: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 journal file (e
99e0: 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f ither.** the [ro
99f0: 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 llback journal]
9a00: 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 or the [write-ah
9a10: 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 ead log]) for a
9a20: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 particular datab
9a30: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
9a40: 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 n. See also [SQ
9a50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f LITE_FCNTL_FILE_
9a60: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 POINTER]..**.**
9a70: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
9a80: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d TL_SYNC_OMITTED]
9a90: 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 ].** No longer i
9aa0: 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 n use..**.** <li
9ab0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
9ac0: 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 SYNC]].** The [S
9ad0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 QLITE_FCNTL_SYNC
9ae0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 ] opcode is gene
9af0: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 rated internally
9b00: 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a by SQLite and.*
9b10: 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 * sent to the VF
9b20: 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 S immediately be
9b30: 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d fore the xSync m
9b40: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 ethod is invoked
9b50: 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 on a.** databas
9b60: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f e file descripto
9b70: 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 r. Or, if the xS
9b80: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f ync method is no
9b90: 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 t invoked .** be
9ba0: 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68 cause the user h
9bb0: 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 as configured SQ
9bc0: 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 Lite with .** [P
9bd0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
9be0: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 s | PRAGMA synch
9bf0: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 ronous=OFF] it i
9c00: 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 s invoked in pla
9c10: 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 ce .** of the xS
9c20: 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d ync method. In m
9c30: 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 ost cases, the p
9c40: 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 ointer argument
9c50: 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 passed with.** t
9c60: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c his file-control
9c70: 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 is NULL. Howeve
9c80: 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61 r, if the databa
9c90: 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 se file is being
9ca0: 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 synced.** as pa
9cb0: 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 rt of a multi-da
9cc0: 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 tabase commit, t
9cd0: 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e he argument poin
9ce0: 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d ts to a nul-term
9cf0: 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 inated.** string
9d00: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
9d10: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 transactions mas
9d20: 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 ter-journal file
9d30: 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 name. VFSes tha
9d40: 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 t .** do not nee
9d50: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 d this signal sh
9d60: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 ould silently ig
9d70: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 nore this opcode
9d80: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a . Applications .
9d90: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 ** should not ca
9da0: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ll [sqlite3_file
9db0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 _control()] with
9dc0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 this opcode as
9dd0: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a doing so may .**
9de0: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 disrupt the ope
9df0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 ration of the sp
9e00: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 ecialized VFSes
9e10: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 that do require
9e20: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e it. .**.** <li>
9e30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 [[SQLITE_FCNTL_C
9e40: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d OMMIT_PHASETWO]]
9e50: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
9e60: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 FCNTL_COMMIT_PHA
9e70: 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 SETWO] opcode is
9e80: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 generated inter
9e90: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a nally by SQLite.
9ea0: 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 ** and sent to t
9eb0: 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74 he VFS after a t
9ec0: 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 ransaction has b
9ed0: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d een committed im
9ee0: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 mediately.** but
9ef0: 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 before the data
9f00: 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 base is unlocked
9f10: 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 . VFSes that do
9f20: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 not need this si
9f30: 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 gnal.** should s
9f40: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 ilently ignore t
9f50: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c his opcode. Appl
9f60: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ications should
9f70: 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c not call.** [sql
9f80: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
9f90: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f l()] with this o
9fa0: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 pcode as doing s
9fb0: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 o may disrupt th
9fc0: 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 e .** operation
9fd0: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a of the specializ
9fe0: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f ed VFSes that do
9ff0: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a require it. .*
a000: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
a010: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 E_FCNTL_WIN32_AV
a020: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 _RETRY]].** ^The
a030: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 [SQLITE_FCNTL_W
a040: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f IN32_AV_RETRY] o
a050: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
a060: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d configure autom
a070: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f atic.** retry co
a080: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 unts and interva
a090: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 ls for certain d
a0a0: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f isk I/O operatio
a0b0: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 ns for the.** wi
a0c0: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f ndows [VFS] in o
a0d0: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 rder to provide
a0e0: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 robustness in th
a0f0: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a e presence of.**
a100: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 anti-virus prog
a110: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c rams. By defaul
a120: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 t, the windows V
a130: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 FS will retry fi
a140: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 le read,.** file
a150: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 write, and file
a160: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f delete operatio
a170: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 ns up to 10 time
a180: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a s, with a delay.
a190: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 ** of 25 millise
a1a0: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 conds before the
a1b0: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 first retry and
a1c0: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 with the delay
a1d0: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 increasing.** by
a1e0: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 an additional 2
a1f0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 5 milliseconds w
a200: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 ith each subsequ
a210: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 ent retry. This
a220: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 .** opcode allow
a230: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 s these two valu
a240: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 es (10 retries a
a250: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e nd 25 millisecon
a260: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 ds of delay).**
a270: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 to be adjusted.
a280: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 The values are
a290: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 changed for all
a2a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
a2b0: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 ions.** within t
a2c0: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e he same process.
a2d0: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 The argument i
a2e0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
a2f0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a n array of two.*
a300: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 * integers where
a310: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 the first integ
a320: 65 72 20 69 73 20 74 68 65 20 6e 65 77 20 72 65 er is the new re
a330: 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 try count and th
a340: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 e second.** inte
a350: 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 ger is the delay
a360: 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 . If either int
a370: 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 eger is negative
a380: 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 , then the setti
a390: 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 ng.** is not cha
a3a0: 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 nged but instead
a3b0: 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 the prior value
a3c0: 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 of that setting
a3d0: 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 is written.** i
a3e0: 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e nto the array en
a3f0: 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 try, allowing th
a400: 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 e current retry
a410: 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a settings to be.*
a420: 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 * interrogated.
a430: 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 The zDbName par
a440: 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 ameter is ignore
a450: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 d..**.** <li>[[S
a460: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 QLITE_FCNTL_PERS
a470: 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 IST_WAL]].** ^Th
a480: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
a490: 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 PERSIST_WAL] opc
a4a0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 ode is used to s
a4b0: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a et or query the.
a4c0: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 ** persistent [W
a4d0: 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 AL | Write Ahead
a4e0: 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 Log] setting.
a4f0: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 By default, the
a500: 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 auxiliary.** wri
a510: 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 te ahead log and
a520: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 shared memory f
a530: 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 iles used for tr
a540: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f ansaction contro
a550: 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 l.** are automat
a560: 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 ically deleted w
a570: 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 hen the latest c
a580: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 onnection to the
a590: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f database.** clo
a5a0: 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 ses. Setting pe
a5b0: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 rsistent WAL mod
a5c0: 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 e causes those f
a5d0: 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 iles to persist
a5e0: 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 after.** close.
a5f0: 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 Persisting the
a600: 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 files is useful
a610: 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 when other proce
a620: 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 sses that do not
a630: 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 .** have write p
a640: 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 ermission on the
a650: 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 directory conta
a660: 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 ining the databa
a670: 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 se file want.**
a680: 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 to read the data
a690: 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 base file, as th
a6a0: 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 e WAL and shared
a6b0: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 memory files mu
a6c0: 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f st exist.** in o
a6d0: 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 rder for the dat
a6e0: 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 abase to be read
a6f0: 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 able. The fourt
a700: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a h parameter to.*
a710: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f * [sqlite3_file_
a720: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 control()] for t
a730: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c his opcode shoul
a740: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 d be a pointer t
a750: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a o an integer..**
a760: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 That integer is
a770: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 0 to disable pe
a780: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 rsistent WAL mod
a790: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 e or 1 to enable
a7a0: 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 persistent.** W
a7b0: 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 AL mode. If the
a7c0: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 integer is -1,
a7d0: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 then it is overw
a7e0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 ritten with the
a7f0: 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 current.** WAL p
a800: 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 ersistence setti
a810: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ng..**.** <li>[[
a820: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 SQLITE_FCNTL_POW
a830: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 ERSAFE_OVERWRITE
a840: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 ]].** ^The [SQLI
a850: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 TE_FCNTL_POWERSA
a860: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 FE_OVERWRITE] op
a870: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 code is used to
a880: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 set or query the
a890: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 .** persistent "
a8a0: 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 powersafe-overwr
a8b0: 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 ite" or "PSOW" s
a8c0: 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f etting. The PSO
a8d0: 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 W setting.** det
a8e0: 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c ermines the [SQL
a8f0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 ITE_IOCAP_POWERS
a900: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 AFE_OVERWRITE] b
a910: 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 it of the.** xDe
a920: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
a930: 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 ics methods. The
a940: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
a950: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 r to.** [sqlite3
a960: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
a970: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 for this opcode
a980: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 should be a poi
a990: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
a9a0: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 er..** That inte
a9b0: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 ger is 0 to disa
a9c0: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 ble zero-damage
a9d0: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 mode or 1 to ena
a9e0: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a ble zero-damage.
a9f0: 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 ** mode. If the
aa00: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 integer is -1,
aa10: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 then it is overw
aa20: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 ritten with the
aa30: 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d current.** zero-
aa40: 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 damage mode sett
aa50: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ing..**.** <li>[
aa60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 [SQLITE_FCNTL_OV
aa70: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 ERWRITE]].** ^Th
aa80: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
aa90: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 OVERWRITE] opcod
aaa0: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 e is invoked by
aab0: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 SQLite after ope
aac0: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 ning.** a write
aad0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 transaction to i
aae0: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e ndicate that, un
aaf0: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 less it is rolle
ab00: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a d back for some.
ab10: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 ** reason, the e
ab20: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 ntire database f
ab30: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 ile will be over
ab40: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 written by the c
ab50: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 urrent .** trans
ab60: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 action. This is
ab70: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f used by VACUUM o
ab80: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a perations..**.**
ab90: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
aba0: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a NTL_VFSNAME]].**
abb0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^The [SQLITE_FC
abc0: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 NTL_VFSNAME] opc
abd0: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ode can be used
abe0: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 to obtain the na
abf0: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 mes of.** all [V
ac00: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 FSes] in the VFS
ac10: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d stack. The nam
ac20: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 es are of all VF
ac30: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a S shims and the.
ac40: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d ** final bottom-
ac50: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 level VFS are wr
ac60: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 itten into memor
ac70: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
ac80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c .** [sqlite3_mal
ac90: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 loc()] and the r
aca0: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 esult is stored
acb0: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 in the char* var
acc0: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 iable.** that th
acd0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
ace0: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 er of [sqlite3_f
acf0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 ile_control()] p
ad00: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 oints to..** The
ad10: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f caller is respo
ad20: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 nsible for freei
ad30: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 ng the memory wh
ad40: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 en done. As wit
ad50: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f h.** all file-co
ad60: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 ntrol actions, t
ad70: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 here is no guara
ad80: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 ntee that this w
ad90: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 ill actually.**
ada0: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 do anything. Ca
adb0: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 llers should ini
adc0: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 tialize the char
add0: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 * variable to a
ade0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 NULL.** pointer
adf0: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c in case this fil
ae00: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 e-control is not
ae10: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 implemented. T
ae20: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c his file-control
ae30: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 .** is intended
ae40: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 for diagnostic u
ae50: 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c se only..**.** <
ae60: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
ae70: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a L_VFS_POINTER]].
ae80: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
ae90: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 FCNTL_VFS_POINTE
aea0: 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 R] opcode finds
aeb0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
aec0: 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 top-level.** [V
aed0: 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 FSes] currently
aee0: 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 in use. ^(The a
aef0: 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 rgument X in.**
af00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
af10: 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 trol(db,SQLITE_F
af20: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 CNTL_VFS_POINTER
af30: 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f ,X) must be.** o
af40: 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 f type "[sqlite3
af50: 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 _vfs] **". This
af60: 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 opcodes will se
af70: 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 t *X.** to a poi
af80: 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d nter to the top-
af90: 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 level VFS.)^.**
afa0: 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 ^When there are
afb0: 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 multiple VFS shi
afc0: 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c ms in the stack,
afd0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e this opcode fin
afe0: 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d ds the.** upper-
aff0: 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a most shim only..
b000: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
b010: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
b020: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 ].** ^Whenever a
b030: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d [PRAGMA] statem
b040: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 ent is parsed, a
b050: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f n [SQLITE_FCNTL_
b060: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 PRAGMA] .** file
b070: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 control is sent
b080: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 to the open [sq
b090: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
b0a0: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 ct corresponding
b0b0: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 .** to the datab
b0c0: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 ase file to whic
b0d0: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 h the pragma sta
b0e0: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e tement refers. ^
b0f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 The argument.**
b100: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 to the [SQLITE_F
b110: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c CNTL_PRAGMA] fil
b120: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 e control is an
b130: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e array of.** poin
b140: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 ters to strings
b150: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 (char**) in whic
b160: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 h the second ele
b170: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 ment of the arra
b180: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 y.** is the name
b190: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 of the pragma a
b1a0: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 nd the third ele
b1b0: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 ment is the argu
b1c0: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 ment to the.** p
b1d0: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 ragma or NULL if
b1e0: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 the pragma has
b1f0: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 no argument. ^T
b200: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 he handler for a
b210: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e n.** [SQLITE_FCN
b220: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 TL_PRAGMA] file
b230: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 control can opti
b240: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 onally make the
b250: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a first element.**
b260: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 of the char** a
b270: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f rgument point to
b280: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e a string obtain
b290: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
b2a0: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f _mprintf()].** o
b2b0: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 r the equivalent
b2c0: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 and that string
b2d0: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 will become the
b2e0: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 result of the p
b2f0: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 ragma or.** the
b300: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 error message if
b310: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c the pragma fail
b320: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 s. ^If the.** [S
b330: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
b340: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c MA] file control
b350: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
b360: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e _NOTFOUND], then
b370: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 normal .** [PRA
b380: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 GMA] processing
b390: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 continues. ^If
b3a0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 the [SQLITE_FCNT
b3b0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c L_PRAGMA].** fil
b3c0: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e e control return
b3d0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 s [SQLITE_OK], t
b3e0: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 hen the parser a
b3f0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a ssumes that the.
b400: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c ** VFS has handl
b410: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 ed the PRAGMA it
b420: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 self and the par
b430: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 ser generates a
b440: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 no-op.** prepare
b450: 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 d statement if r
b460: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 esult string is
b470: 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 NULL, or that re
b480: 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 turns a copy.**
b490: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 of the result st
b4a0: 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 ring if the stri
b4b0: 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a ng is non-NULL..
b4c0: 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 ** ^If the [SQLI
b4d0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
b4e0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 file control re
b4f0: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 turns.** any res
b500: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 ult code other t
b510: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 han [SQLITE_OK]
b520: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f or [SQLITE_NOTFO
b530: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 UND], that means
b540: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 .** that the VFS
b550: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 encountered an
b560: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 error while hand
b570: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 ling the [PRAGMA
b580: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d ] and the.** com
b590: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 pilation of the
b5a0: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 PRAGMA fails wit
b5b0: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 h an error. ^Th
b5c0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
b5d0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 PRAGMA].** file
b5e0: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 control occurs a
b5f0: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 t the beginning
b600: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d of pragma statem
b610: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 ent analysis and
b620: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c so.** it is abl
b630: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 e to override bu
b640: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 ilt-in [PRAGMA]
b650: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a statements..**.*
b660: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
b670: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 CNTL_BUSYHANDLER
b680: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 ]].** ^The [SQLI
b690: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e TE_FCNTL_BUSYHAN
b6a0: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f DLER].** file-co
b6b0: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 ntrol may be inv
b6c0: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f oked by SQLite o
b6d0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 n the database f
b6e0: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 ile handle.** sh
b6f0: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 ortly after it i
b700: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 s opened in orde
b710: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 r to provide a c
b720: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 ustom VFS with a
b730: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 ccess.** to the
b740: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 connections busy
b750: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 -handler callbac
b760: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 k. The argument
b770: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 is of type (void
b780: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 **).** - an arr
b790: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 ay of two (void
b7a0: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 *) values. The f
b7b0: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 irst (void *) ac
b7c0: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a tually points.**
b7d0: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f to a function o
b7e0: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 f type (int (*)(
b7f0: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 void *)). In ord
b800: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 er to invoke the
b810: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 connections.**
b820: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 busy-handler, th
b830: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 is function shou
b840: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 ld be invoked wi
b850: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 th the second (v
b860: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 oid *) in.** the
b870: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e array as the on
b880: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 ly argument. If
b890: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a it returns non-z
b8a0: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 ero, then the op
b8b0: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c eration.** shoul
b8c0: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 d be retried. If
b8d0: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f it returns zero
b8e0: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 , the custom VFS
b8f0: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 should abandon
b900: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f the.** current o
b910: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 peration..**.**
b920: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
b930: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d TL_TEMPFILENAME]
b940: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f ].** ^Applicatio
b950: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 n can invoke the
b960: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 [SQLITE_FCNTL_T
b970: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c EMPFILENAME] fil
b980: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 e-control.** to
b990: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 have SQLite gene
b9a0: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 rate a.** tempor
b9b0: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 ary filename usi
b9c0: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f ng the same algo
b9d0: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f rithm that is fo
b9e0: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 llowed to genera
b9f0: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 te.** temporary
ba00: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 filenames for TE
ba10: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 MP tables and ot
ba20: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 her internal use
ba30: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d s. The.** argum
ba40: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 ent should be a
ba50: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c char** which wil
ba60: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 l be filled with
ba70: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a the filename.**
ba80: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 written into me
ba90: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
baa0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
bab0: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c oc()]. The call
bac0: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 er should.** inv
bad0: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 oke [sqlite3_fre
bae0: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 e()] on the resu
baf0: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 lt to avoid a me
bb00: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a mory leak..**.**
bb10: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
bb20: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a NTL_MMAP_SIZE]].
bb30: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
bb40: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 CNTL_MMAP_SIZE]
bb50: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 file control is
bb60: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 used to query or
bb70: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 set the.** maxi
bb80: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 mum number of by
bb90: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 tes that will be
bba0: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 used for memory
bbb0: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 -mapped I/O..**
bbc0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 The argument is
bbd0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 a pointer to a v
bbe0: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c alue of type sql
bbf0: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a ite3_int64 that.
bc00: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 ** is an advisor
bc10: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 y maximum number
bc20: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
bc30: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 file to memory
bc40: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 map. The.** poi
bc50: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 nter is overwrit
bc60: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 ten with the old
bc70: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d value. The lim
bc80: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 it is not change
bc90: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 d if.** the valu
bca0: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 e originally poi
bcb0: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 nted to is negat
bcc0: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 ive, and so the
bcd0: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a current limit .*
bce0: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 * can be queried
bcf0: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 by passing in a
bd00: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 pointer to a ne
bd10: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 gative number.
bd20: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e This.** file-con
bd30: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 trol is used int
bd40: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 ernally to imple
bd50: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 ment [PRAGMA mma
bd60: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c p_size]..**.** <
bd70: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
bd80: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 L_TRACE]].** The
bd90: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 [SQLITE_FCNTL_T
bda0: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 RACE] file contr
bdb0: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 ol provides advi
bdc0: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e sory information
bdd0: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 .** to the VFS a
bde0: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69 bout what the hi
bdf0: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 gher layers of t
be00: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 he SQLite stack
be10: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 are doing..** Th
be20: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 is file control
be30: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 is used by some
be40: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61 VFS activity tra
be50: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a cing [shims]..**
be60: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 The argument is
be70: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
be80: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 ed string. High
be90: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 er layers in the
bea0: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b .** SQLite stack
beb0: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e may generate in
bec0: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 stances of this
bed0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a file control if.
bee0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 ** the [SQLITE_U
bef0: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 SE_FCNTL_TRACE]
bf00: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
bf10: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a ion is enabled..
bf20: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
bf30: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 TE_FCNTL_HAS_MOV
bf40: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ED]].** The [SQL
bf50: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f ITE_FCNTL_HAS_MO
bf60: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f VED] file contro
bf70: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 l interprets its
bf80: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a argument as a.*
bf90: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 * pointer to an
bfa0: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 integer and it w
bfb0: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 rites a boolean
bfc0: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 into that intege
bfd0: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f r depending.** o
bfe0: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 n whether or not
bff0: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 the file has be
c000: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 en renamed, move
c010: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 d, or deleted si
c020: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 nce it.** was fi
c030: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a rst opened..**.*
c040: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
c050: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 CNTL_WIN32_GET_H
c060: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b ANDLE]].** The [
c070: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
c080: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 32_GET_HANDLE] o
c090: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 pcode can be use
c0a0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a d to obtain the.
c0b0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 ** underlying na
c0c0: 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 tive file handle
c0d0: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
c0e0: 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 a file handle.
c0f0: 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f This file.** co
c100: 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 ntrol interprets
c110: 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 its argument as
c120: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
c130: 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 native file hand
c140: 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 le and.** writes
c150: 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76 the resulting v
c160: 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a alue there..**.*
c170: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
c180: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 CNTL_WIN32_SET_H
c190: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b ANDLE]].** The [
c1a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
c1b0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 32_SET_HANDLE] o
c1c0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f pcode is used fo
c1d0: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 r debugging. Th
c1e0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 is.** opcode cau
c1f0: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e ses the xFileCon
c200: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 trol method to s
c210: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e wap the file han
c220: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 dle with the one
c230: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 .** pointed to b
c240: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d y the pArg argum
c250: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 ent. This capab
c260: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75 ility is used du
c270: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 ring testing.**
c280: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 and only needs t
c290: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 o be supported w
c2a0: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 hen SQLITE_TEST
c2b0: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a is defined..**.*
c2c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
c2d0: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d CNTL_WAL_BLOCK]]
c2e0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
c2f0: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d FCNTL_WAL_BLOCK]
c300: 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 is a signal to
c310: 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 the VFS layer th
c320: 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 at it might.** b
c330: 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 e advantageous t
c340: 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e o block on the n
c350: 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 ext WAL lock if
c360: 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 the lock is not
c370: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 immediately.** a
c380: 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 vailable. The W
c390: 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 AL subsystem iss
c3a0: 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 ues this signal
c3b0: 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 during rare.** c
c3c0: 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 ircumstances in
c3d0: 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 order to fix a p
c3e0: 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f roblem with prio
c3f0: 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a rity inversion..
c400: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** Applications
c410: 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f should <em>not</
c420: 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c em> use this fil
c430: 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a e-control..**.**
c440: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
c450: 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 NTL_ZIPVFS]].**
c460: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
c470: 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 L_ZIPVFS] opcode
c480: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 is implemented
c490: 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 by zipvfs only.
c4a0: 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 All other.** VFS
c4b0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 should return S
c4c0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 QLITE_NOTFOUND f
c4d0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a or this opcode..
c4e0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
c4f0: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a TE_FCNTL_RBU]].*
c500: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
c510: 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 NTL_RBU] opcode
c520: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 is implemented b
c530: 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 y the special VF
c540: 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 S used by.** the
c550: 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f RBU extension o
c560: 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 nly. All other
c570: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 VFS should retur
c580: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e n SQLITE_NOTFOUN
c590: 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 D for.** this op
c5a0: 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c code. .**.** <l
c5b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
c5c0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 _BEGIN_ATOMIC_WR
c5d0: 49 54 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20 ITE]].** If the
c5e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 [SQLITE_FCNTL_BE
c5f0: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 GIN_ATOMIC_WRITE
c600: 5d 20 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73 ] opcode returns
c610: 20 53 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e SQLITE_OK, then
c620: 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 .** the file des
c630: 63 72 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65 criptor is place
c640: 64 20 69 6e 20 22 62 61 74 63 68 20 77 72 69 74 d in "batch writ
c650: 65 20 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a e mode", which.*
c660: 2a 20 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73 * means all subs
c670: 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 equent write ope
c680: 72 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20 rations will be
c690: 64 65 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e deferred and don
c6a0: 65 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20 e.** atomically
c6b0: 61 74 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c at the next [SQL
c6c0: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 ITE_FCNTL_COMMIT
c6d0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20 _ATOMIC_WRITE].
c6e0: 20 53 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74 Systems.** that
c6f0: 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 do not support
c700: 62 61 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69 batch atomic wri
c710: 74 65 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 tes will return
c720: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e SQLITE_NOTFOUND.
c730: 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 .** ^Following a
c740: 20 73 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49 successful SQLI
c750: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 TE_FCNTL_BEGIN_A
c760: 54 4f 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20 TOMIC_WRITE and
c770: 70 72 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20 prior to.** the
c780: 63 6c 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f closing [SQLITE_
c790: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f FCNTL_COMMIT_ATO
c7a0: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a MIC_WRITE] or.**
c7b0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 [SQLITE_FCNTL_R
c7c0: 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 OLLBACK_ATOMIC_W
c7d0: 52 49 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69 RITE], SQLite wi
c7e0: 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 ll make.** no VF
c7f0: 53 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c S interface call
c800: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73 s on the same [s
c810: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c qlite3_file] fil
c820: 65 20 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20 e descriptor.**
c830: 65 78 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73 except for calls
c840: 20 74 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d to the xWrite m
c850: 65 74 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46 ethod and the xF
c860: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
c870: 64 0a 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54 d.** with [SQLIT
c880: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e E_FCNTL_SIZE_HIN
c890: 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b T]..**.** <li>[[
c8a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d SQLITE_FCNTL_COM
c8b0: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 MIT_ATOMIC_WRITE
c8c0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
c8d0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 E_FCNTL_COMMIT_A
c8e0: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 TOMIC_WRITE] opc
c8f0: 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77 ode causes all w
c900: 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f rite.** operatio
c910: 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72 65 ns since the pre
c920: 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c vious successful
c930: 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 call to .** [SQ
c940: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e LITE_FCNTL_BEGIN
c950: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 _ATOMIC_WRITE] t
c960: 6f 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61 o be performed a
c970: 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 tomically..** Th
c980: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 is file control
c990: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
c9a0: 4f 4b 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 OK] if and only
c9b0: 69 66 20 74 68 65 20 77 72 69 74 65 73 20 77 65 if the writes we
c9c0: 72 65 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72 re.** all perfor
c9d0: 6d 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 med successfully
c9e0: 20 61 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63 and have been c
c9f0: 6f 6d 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73 ommitted to pers
ca00: 69 73 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a istent storage..
ca10: 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f ** ^Regardless o
ca20: 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
ca30: 20 69 74 20 69 73 20 73 75 63 63 65 73 73 66 75 it is successfu
ca40: 6c 2c 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e l, this file con
ca50: 74 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68 trol takes.** th
ca60: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f e file descripto
ca70: 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77 r out of batch w
ca80: 72 69 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61 rite mode so tha
ca90: 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 t all subsequent
caa0: 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74 .** write operat
cab0: 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e ions are indepen
cac0: 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 dent..** ^SQLite
cad0: 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f will never invo
cae0: 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ke SQLITE_FCNTL_
caf0: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 COMMIT_ATOMIC_WR
cb00: 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 ITE without.** a
cb10: 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 prior successfu
cb20: 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 l call to [SQLIT
cb30: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 E_FCNTL_BEGIN_AT
cb40: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a OMIC_WRITE]..**.
cb50: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
cb60: 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 FCNTL_ROLLBACK_A
cb70: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a TOMIC_WRITE]].**
cb80: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
cb90: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d TL_ROLLBACK_ATOM
cba0: 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 IC_WRITE] opcode
cbb0: 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74 causes all writ
cbc0: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 e.** operations
cbd0: 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f since the previo
cbe0: 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 us successful ca
cbf0: 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 ll to .** [SQLIT
cc00: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 E_FCNTL_BEGIN_AT
cc10: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 OMIC_WRITE] to b
cc20: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a e rolled back..*
cc30: 2a 20 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e * ^This file con
cc40: 74 72 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66 trol takes the f
cc50: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f ile descriptor o
cc60: 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 74 ut of batch writ
cc70: 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61 e mode.** so tha
cc80: 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 t all subsequent
cc90: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e write operation
cca0: 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e s are independen
ccb0: 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 t..** ^SQLite wi
ccc0: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 ll never invoke
ccd0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c SQLITE_FCNTL_ROL
cce0: 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 LBACK_ATOMIC_WRI
ccf0: 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 TE without.** a
cd00: 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c prior successful
cd10: 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 call to [SQLITE
cd20: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f _FCNTL_BEGIN_ATO
cd30: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a MIC_WRITE]..**.*
cd40: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
cd50: 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 CNTL_LOCK_TIMEOU
cd60: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 T]].** The [SQLI
cd70: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 TE_FCNTL_LOCK_TI
cd80: 4d 45 4f 55 54 5d 20 6f 70 63 6f 64 65 20 63 61 MEOUT] opcode ca
cd90: 75 73 65 73 20 61 74 74 65 6d 70 74 73 20 74 6f uses attempts to
cda0: 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 20 66 69 6c obtain.** a fil
cdb0: 65 20 6c 6f 63 6b 20 75 73 69 6e 67 20 74 68 65 e lock using the
cdc0: 20 78 4c 6f 63 6b 20 6f 72 20 78 53 68 6d 4c 6f xLock or xShmLo
cdd0: 63 6b 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 ck methods of th
cde0: 65 20 56 46 53 20 74 6f 20 77 61 69 74 0a 2a 2a e VFS to wait.**
cdf0: 20 66 6f 72 20 75 70 20 74 6f 20 4d 20 6d 69 6c for up to M mil
ce00: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 liseconds before
ce10: 20 66 61 69 6c 69 6e 67 2c 20 77 68 65 72 65 20 failing, where
ce20: 4d 20 69 73 20 74 68 65 20 73 69 6e 67 6c 65 20 M is the single
ce30: 0a 2a 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 .** unsigned int
ce40: 65 67 65 72 20 70 61 72 61 6d 65 74 65 72 2e 0a eger parameter..
ce50: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </ul>.*/.#def
ce60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
ce70: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 _LOCKSTATE
ce80: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 1.#defi
ce90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
cea0: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c GET_LOCKPROXYFIL
ceb0: 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e E 2.#defin
cec0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 e SQLITE_FCNTL_S
ced0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 ET_LOCKPROXYFILE
cee0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
cef0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 SQLITE_FCNTL_LA
cf00: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 ST_ERRNO
cf10: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 4.#define
cf20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a SQLITE_FCNTL_SIZ
cf30: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 E_HINT
cf40: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 5.#define S
cf50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e QLITE_FCNTL_CHUN
cf60: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 K_SIZE
cf70: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 6.#define SQ
cf80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f LITE_FCNTL_FILE_
cf90: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 POINTER
cfa0: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 7.#define SQL
cfb0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f ITE_FCNTL_SYNC_O
cfc0: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20 MITTED
cfd0: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8.#define SQLI
cfe0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 TE_FCNTL_WIN32_A
cff0: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20 V_RETRY
d000: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 9.#define SQLIT
d010: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f E_FCNTL_PERSIST_
d020: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 WAL 1
d030: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
d040: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 _FCNTL_OVERWRITE
d050: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31 11
d060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d070: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 FCNTL_VFSNAME
d080: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 12.
d090: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
d0a0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f CNTL_POWERSAFE_O
d0b0: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 VERWRITE 13.#
d0c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
d0d0: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 NTL_PRAGMA
d0e0: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 14.#d
d0f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
d100: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 TL_BUSYHANDLER
d110: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 15.#de
d120: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
d130: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 L_TEMPFILENAME
d140: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 16.#def
d150: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
d160: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 _MMAP_SIZE
d170: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 18.#defi
d180: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
d190: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20 TRACE
d1a0: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 19.#defin
d1b0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 e SQLITE_FCNTL_H
d1c0: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 AS_MOVED
d1d0: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20.#define
d1e0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 SQLITE_FCNTL_SY
d1f0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 NC
d200: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 21.#define
d210: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d SQLITE_FCNTL_COM
d220: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 MIT_PHASETWO
d230: 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 22.#define S
d240: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 QLITE_FCNTL_WIN3
d250: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 2_SET_HANDLE
d260: 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 23.#define SQ
d270: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 LITE_FCNTL_WAL_B
d280: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 LOCK
d290: 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 24.#define SQL
d2a0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 ITE_FCNTL_ZIPVFS
d2b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
d2c0: 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 25.#define SQLI
d2d0: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 TE_FCNTL_RBU
d2e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
d2f0: 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 26.#define SQLIT
d300: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e E_FCNTL_VFS_POIN
d310: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32 TER 2
d320: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 7.#define SQLITE
d330: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 _FCNTL_JOURNAL_P
d340: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 OINTER 28
d350: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d360: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f FCNTL_WIN32_GET_
d370: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a HANDLE 29.
d380: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
d390: 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20 CNTL_PDB
d3a0: 20 20 20 20 20 20 20 20 20 20 20 20 33 30 0a 23 30.#
d3b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
d3c0: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 NTL_BEGIN_ATOMIC
d3d0: 5f 57 52 49 54 45 20 20 20 20 20 33 31 0a 23 64 _WRITE 31.#d
d3e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
d3f0: 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 TL_COMMIT_ATOMIC
d400: 5f 57 52 49 54 45 20 20 20 20 33 32 0a 23 64 65 _WRITE 32.#de
d410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
d420: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 L_ROLLBACK_ATOMI
d430: 43 5f 57 52 49 54 45 20 20 33 33 0a 23 64 65 66 C_WRITE 33.#def
d440: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
d450: 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 20 20 20 _LOCK_TIMEOUT
d460: 20 20 20 20 20 20 20 20 33 34 0a 0a 2f 2a 20 64 34../* d
d470: 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 eprecated names
d480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
d490: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 E_GET_LOCKPROXYF
d4a0: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f ILE SQLITE_
d4b0: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 FCNTL_GET_LOCKPR
d4c0: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 OXYFILE.#define
d4d0: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 SQLITE_SET_LOCKP
d4e0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 ROXYFILE SQ
d4f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c LITE_FCNTL_SET_L
d500: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 OCKPROXYFILE.#de
d510: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 fine SQLITE_LAST
d520: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 _ERRNO
d530: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f SQLITE_FCNTL_
d540: 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a LAST_ERRNO.../*.
d550: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 ** CAPI3REF: Mut
d560: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 ex Handle.**.**
d570: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 The mutex module
d580: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 within SQLite d
d590: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f efines [sqlite3_
d5a0: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a mutex] to be an.
d5b0: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 ** abstract type
d5c0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a for a mutex obj
d5d0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 ect. The SQLite
d5e0: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b core never look
d5f0: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 s.** at the inte
d600: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 rnal representat
d610: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 ion of an [sqlit
d620: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f e3_mutex]. It o
d630: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 nly.** deals wit
d640: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 h pointers to th
d650: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
d660: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 ] object..**.**
d670: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 Mutexes are crea
d680: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
d690: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 e3_mutex_alloc()
d6a0: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 ]..*/.typedef st
d6b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 ruct sqlite3_mut
d6c0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ex sqlite3_mutex
d6d0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
d6e0: 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 F: Loadable Exte
d6f0: 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a nsion Thunk.**.*
d700: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 * A pointer to t
d710: 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65 he opaque sqlite
d720: 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 3_api_routines s
d730: 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73 73 tructure is pass
d740: 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 ed as.** the thi
d750: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
d760: 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 entry points of
d770: 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 [loadable extens
d780: 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 ions]. This.**
d790: 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 62 structure must b
d7a0: 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f e typedefed in o
d7b0: 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f rder to work aro
d7c0: 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 und compiler war
d7d0: 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 nings.** on some
d7e0: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 platforms..*/.t
d7f0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
d800: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e lite3_api_routin
d810: 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 es sqlite3_api_r
d820: 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 outines;../*.**
d830: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 CAPI3REF: OS Int
d840: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a erface Object.**
d850: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
d860: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 of the sqlite3_v
d870: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 fs object define
d880: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 s the interface
d890: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 between.** the S
d8a0: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 QLite core and t
d8b0: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 he underlying op
d8c0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 erating system.
d8d0: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e The "vfs".** in
d8e0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
d8f0: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 object stands f
d900: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 or "virtual file
d910: 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a system". See.*
d920: 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 * the [VFS | VFS
d930: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 documentation]
d940: 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f for further info
d950: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 rmation..**.** T
d960: 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 he VFS interface
d970: 20 69 73 20 73 6f 6d 65 74 69 6d 65 73 20 65 78 is sometimes ex
d980: 74 65 6e 64 65 64 20 62 79 20 61 64 64 69 6e 67 tended by adding
d990: 20 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74 new methods ont
d9a0: 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20 45 o.** the end. E
d9b0: 61 63 68 20 74 69 6d 65 20 73 75 63 68 20 61 6e ach time such an
d9c0: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72 extension occur
d9d0: 73 2c 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 s, the iVersion
d9e0: 66 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72 field.** is incr
d9f0: 65 6d 65 6e 74 65 64 2e 20 20 54 68 65 20 69 56 emented. The iV
da00: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 73 74 61 ersion value sta
da10: 72 74 65 64 20 6f 75 74 20 61 73 20 31 20 69 6e rted out as 1 in
da20: 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 .** SQLite [vers
da30: 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64 ion 3.5.0] on [d
da40: 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68 ateof:3.5.0], th
da50: 65 6e 20 69 6e 63 72 65 61 73 65 64 20 74 6f 20 en increased to
da60: 32 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69 74 65 2.** with SQLite
da70: 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d [version 3.7.0]
da80: 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e on [dateof:3.7.
da90: 30 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e 63 0], and then inc
daa0: 72 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77 reased.** to 3 w
dab0: 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73 ith SQLite [vers
dac0: 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64 ion 3.7.6] on [d
dad0: 61 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41 ateof:3.7.6]. A
dae0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
daf0: 0a 2a 2a 20 6d 61 79 20 62 65 20 61 70 70 65 6e .** may be appen
db00: 64 65 64 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ded to the sqlit
db10: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 61 6e e3_vfs object an
db20: 64 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 d the iVersion v
db30: 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72 alue.** may incr
db40: 65 61 73 65 20 61 67 61 69 6e 20 69 6e 20 66 75 ease again in fu
db50: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
db60: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65 SQLite..** Note
db70: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 that the struct
db80: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 ure.** of the sq
db90: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 lite3_vfs object
dba0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 changes in the
dbb0: 74 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a transition from.
dbc0: 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 ** SQLite [versi
dbd0: 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65 on 3.5.9] to [ve
dbe0: 72 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20 rsion 3.6.0] on
dbf0: 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a [dateof:3.6.0].*
dc00: 2a 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 * and yet the iV
dc10: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 ersion field was
dc20: 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a not modified..*
dc30: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c *.** The szOsFil
dc40: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 e field is the s
dc50: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c ize of the subcl
dc60: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 assed [sqlite3_f
dc70: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 ile].** structur
dc80: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 e used by this V
dc90: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 FS. mxPathname
dca0: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c is the maximum l
dcb0: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 ength of.** a pa
dcc0: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 thname in this V
dcd0: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 FS..**.** Regist
dce0: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 ered sqlite3_vfs
dcf0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 objects are kep
dd00: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 t on a linked li
dd10: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 st formed by.**
dd20: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 the pNext pointe
dd30: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 r. The [sqlite3
dd40: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d _vfs_register()]
dd50: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
dd60: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 _vfs_unregister(
dd70: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 )] interfaces ma
dd80: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a nage this list.*
dd90: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 * in a thread-sa
dda0: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 fe way. The [sq
ddb0: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 lite3_vfs_find()
ddc0: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 ] interface.** s
ddd0: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 earches the list
dde0: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 . Neither the a
ddf0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 pplication code
de00: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 nor the VFS.** i
de10: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 mplementation sh
de20: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 ould use the pNe
de30: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a xt pointer..**.*
de40: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c * The pNext fiel
de50: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 d is the only fi
de60: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 eld in the sqlit
de70: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 e3_vfs.** struct
de80: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 ure that SQLite
de90: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 will ever modify
dea0: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f . SQLite will o
deb0: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 nly access.** or
dec0: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 modify this fie
ded0: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 ld while holding
dee0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 a particular st
def0: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 atic mutex..** T
df00: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
df10: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 hould never modi
df20: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 fy anything with
df30: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 in the sqlite3_v
df40: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 fs.** object onc
df50: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 e the object has
df60: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 been registered
df70: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d ..**.** The zNam
df80: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 e field holds th
df90: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 e name of the VF
dfa0: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e S module. The n
dfb0: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 ame must.** be u
dfc0: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c nique across all
dfd0: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a VFS modules..**
dfe0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 .** [[sqlite3_vf
dff0: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 s.xOpen]].** ^SQ
e000: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 Lite guarantees
e010: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 that the zFilena
e020: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 me parameter to
e030: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 xOpen.** is eith
e040: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 er a NULL pointe
e050: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 r or string obta
e060: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 ined.** from xFu
e070: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 llPathname() wit
e080: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 h an optional su
e090: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e ffix added..** ^
e0a0: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 If a suffix is a
e0b0: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c dded to the zFil
e0c0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c ename parameter,
e0d0: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 it will.** cons
e0e0: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 ist of a single
e0f0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f "-" character fo
e100: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 llowed by no mor
e110: 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 e than.** 11 alp
e120: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 hanumeric and/or
e130: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e "-" characters.
e140: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 .** ^SQLite furt
e150: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 her guarantees t
e160: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e hat.** the strin
e170: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 g will be valid
e180: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e and unchanged un
e190: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a til xClose() is.
e1a0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 ** called. Becau
e1b0: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f se of the previo
e1c0: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 us sentence,.**
e1d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
e1e0: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 e] can safely st
e1f0: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ore a pointer to
e200: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 the.** filename
e210: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 if it needs to
e220: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c remember the fil
e230: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 ename for some r
e240: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 eason..** If the
e250: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d zFilename param
e260: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 eter to xOpen is
e270: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
e280: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 then xOpen.** mu
e290: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 st invent its ow
e2a0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 n temporary name
e2b0: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 for the file.
e2c0: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a ^Whenever the .*
e2d0: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 * xFilename para
e2e0: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 meter is NULL it
e2f0: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 will also be th
e300: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a e case that the.
e310: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 ** flags paramet
e320: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 er will include
e330: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c [SQLITE_OPEN_DEL
e340: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a ETEONCLOSE]..**.
e350: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 ** The flags arg
e360: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 ument to xOpen()
e370: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 includes all bi
e380: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 ts set in.** the
e390: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
e3a0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
e3b0: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b _v2()]. Or if [
e3c0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a sqlite3_open()].
e3d0: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f ** or [sqlite3_o
e3e0: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 pen16()] is used
e3f0: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 , then flags inc
e400: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a ludes at least.*
e410: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 * [SQLITE_OPEN_R
e420: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c EADWRITE] | [SQL
e430: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d ITE_OPEN_CREATE]
e440: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 . .** If xOpen()
e450: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 opens a file re
e460: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 ad-only then it
e470: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 sets *pOutFlags
e480: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 to.** include [S
e490: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
e4a0: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 NLY]. Other bit
e4b0: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 s in *pOutFlags
e4c0: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a may be set..**.*
e4d0: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 * ^(SQLite will
e4e0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 also add one of
e4f0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c the following fl
e500: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e ags to the xOpen
e510: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 ().** call, depe
e520: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a nding on the obj
e530: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 ect being opened
e540: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
e550: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
e560: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c EN_MAIN_DB].** <
e570: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
e580: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a N_MAIN_JOURNAL].
e590: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
e5a0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a _OPEN_TEMP_DB].*
e5b0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
e5c0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
e5d0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
e5e0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 ITE_OPEN_TRANSIE
e5f0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 NT_DB].** <li>
e600: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 [SQLITE_OPEN_SUB
e610: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
e620: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d [SQLITE_OPEN_M
e630: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a ASTER_JOURNAL].*
e640: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
e650: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 OPEN_WAL].** </u
e660: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 l>)^.**.** The f
e670: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e ile I/O implemen
e680: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 tation can use t
e690: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 he object type f
e6a0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 lags to.** chang
e6b0: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 e the way it dea
e6c0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 ls with files.
e6d0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 For example, an
e6e0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 application.** t
e6f0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 hat does not car
e700: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 e about crash re
e710: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 covery or rollba
e720: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a ck might make.**
e730: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a the open of a j
e740: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f ournal file a no
e750: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 -op. Writes to
e760: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 this journal wou
e770: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f ld.** also be no
e780: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 -ops, and any at
e790: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 tempt to read th
e7a0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 e journal would
e7b0: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 return.** SQLITE
e7c0: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 _IOERR. Or the
e7d0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d implementation m
e7e0: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 ight recognize t
e7f0: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a hat a database.*
e800: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 * file will be d
e810: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 oing page-aligne
e820: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 d sector reads a
e830: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 nd writes in a r
e840: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 andom.** order a
e850: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f nd set up its I/
e860: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f O subsystem acco
e870: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 rdingly..**.** S
e880: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f QLite might also
e890: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 add one of the
e8a0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 following flags
e8b0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 to the xOpen met
e8c0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a hod:.**.** <ul>.
e8d0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
e8e0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
e8f0: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c SE].** <li> [SQL
e900: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
e910: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a VE].** </ul>.**.
e920: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f ** The [SQLITE_O
e930: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
e940: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 E] flag means th
e950: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 e file should be
e960: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e .** deleted when
e970: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 it is closed.
e980: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 ^The [SQLITE_OPE
e990: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
e9a0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 .** will be set
e9b0: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 for TEMP databas
e9c0: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 es and their jou
e9d0: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 rnals, transient
e9e0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 .** databases, a
e9f0: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a nd subjournals..
ea00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 **.** ^The [SQLI
ea10: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 TE_OPEN_EXCLUSIV
ea20: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 E] flag is alway
ea30: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e s used in conjun
ea40: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 ction.** with th
ea50: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 e [SQLITE_OPEN_C
ea60: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 REATE] flag, whi
ea70: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 ch are both dire
ea80: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 ctly.** analogou
ea90: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 s to the O_EXCL
eaa0: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 and O_CREAT flag
eab0: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f s of the POSIX o
eac0: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 pen().** API. T
ead0: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 he SQLITE_OPEN_E
eae0: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 XCLUSIVE flag, w
eaf0: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 hen paired with
eb00: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f the .** SQLITE_O
eb10: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 PEN_CREATE, is u
eb20: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 sed to indicate
eb30: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 that file should
eb40: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 always.** be cr
eb50: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 eated, and that
eb60: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 it is an error i
eb70: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 f it already exi
eb80: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 sts..** It is <i
eb90: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f >not</i> used to
eba0: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 indicate the fi
ebb0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 le should be ope
ebc0: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c ned .** for excl
ebd0: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a usive access..**
ebe0: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a .** ^At least sz
ebf0: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 OsFile bytes of
ec00: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 memory are alloc
ec10: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a ated by SQLite.*
ec20: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b * to hold the [
ec30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 sqlite3_file] st
ec40: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 ructure passed a
ec50: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 s the third.** a
ec60: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e rgument to xOpen
ec70: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 . The xOpen met
ec80: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 hod does not hav
ec90: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 e to.** allocate
eca0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 the structure;
ecb0: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 it should just f
ecc0: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 ill it in. Note
ecd0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 that.** the xOp
ece0: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 en method must s
ecf0: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 et the sqlite3_f
ed00: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 ile.pMethods to
ed10: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 either.** a vali
ed20: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 d [sqlite3_io_me
ed30: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 thods] object or
ed40: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e to NULL. xOpen
ed50: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 must do.** this
ed60: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 even if the ope
ed70: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 n fails. SQLite
ed80: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 expects that th
ed90: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 e sqlite3_file.p
eda0: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 Methods.** eleme
edb0: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 nt will be valid
edc0: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 after xOpen ret
edd0: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 urns regardless
ede0: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a of the success.*
edf0: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 * or failure of
ee00: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a the xOpen call..
ee10: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f **.** [[sqlite3_
ee20: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a vfs.xAccess]].**
ee30: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 ^The flags argu
ee40: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 ment to xAccess(
ee50: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 ) may be [SQLITE
ee60: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a _ACCESS_EXISTS].
ee70: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 ** to test for t
ee80: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 he existence of
ee90: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 a file, or [SQLI
eea0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 TE_ACCESS_READWR
eeb0: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 ITE] to.** test
eec0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 whether a file i
eed0: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 s readable and w
eee0: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c ritable, or [SQL
eef0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d ITE_ACCESS_READ]
ef00: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 .** to test whet
ef10: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 her a file is at
ef20: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e least readable.
ef30: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 The file can
ef40: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 be a.** director
ef50: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 y..**.** ^SQLite
ef60: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c will always all
ef70: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d ocate at least m
ef80: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 xPathname+1 byte
ef90: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 s for the.** out
efa0: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c put buffer xFull
efb0: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 Pathname. The e
efc0: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 xact size of the
efd0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a output buffer.*
efe0: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 * is also passed
eff0: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 as a parameter
f000: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 to both methods
f010: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 . If the output
f020: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 buffer.** is not
f030: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b large enough, [
f040: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d SQLITE_CANTOPEN]
f050: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 should be retur
f060: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 ned. Since this
f070: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 is.** handled as
f080: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 a fatal error b
f090: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d y SQLite, vfs im
f0a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 plementations sh
f0b0: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a ould endeavor.**
f0c0: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 to prevent this
f0d0: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 by setting mxPa
f0e0: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 thname to a suff
f0f0: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 iciently large v
f100: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 alue..**.** The
f110: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 xRandomness(), x
f120: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e Sleep(), xCurren
f130: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 tTime(), and xCu
f140: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 rrentTimeInt64()
f150: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 .** interfaces a
f160: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 re not strictly
f170: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 a part of the fi
f180: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 lesystem, but th
f190: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 ey are.** includ
f1a0: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 ed in the VFS st
f1b0: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 ructure for comp
f1c0: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 leteness..** The
f1d0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 xRandomness() f
f1e0: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 unction attempts
f1f0: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 to return nByte
f200: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f s bytes.** of go
f210: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f od-quality rando
f220: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e mness into zOut.
f230: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c The return val
f240: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 ue is.** the act
f250: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 ual number of by
f260: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 tes of randomnes
f270: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 s obtained..** T
f280: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 he xSleep() meth
f290: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 od causes the ca
f2a0: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 lling thread to
f2b0: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 sleep for at.**
f2c0: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 least the number
f2d0: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 of microseconds
f2e0: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 given. ^The xC
f2f0: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 urrentTime().**
f300: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 method returns a
f310: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 Julian Day Numb
f320: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 er for the curre
f330: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 nt date and time
f340: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e as.** a floatin
f350: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a g point value..*
f360: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 * ^The xCurrentT
f370: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f imeInt64() metho
f380: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e d returns, as an
f390: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 integer, the Ju
f3a0: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 lian.** Day Numb
f3b0: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 er multiplied by
f3c0: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 86400000 (the n
f3d0: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 umber of millise
f3e0: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 conds in .** a 2
f3f0: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 4-hour day). .*
f400: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 * ^SQLite will u
f410: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 se the xCurrentT
f420: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f imeInt64() metho
f430: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 d to get the cur
f440: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 rent.** date and
f450: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 time if that me
f460: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c thod is availabl
f470: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 e (if iVersion i
f480: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 s 2 or .** great
f490: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 er and the funct
f4a0: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e ion pointer is n
f4b0: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c ot NULL) and wil
f4c0: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 l fall back.** t
f4d0: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 o xCurrentTime()
f4e0: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 if xCurrentTime
f4f0: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 Int64() is unava
f500: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ilable..**.** ^T
f510: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c he xSetSystemCal
f520: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 l(), xGetSystemC
f530: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 all(), and xNest
f540: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 SystemCall() int
f550: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e erfaces.** are n
f560: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 ot used by the S
f570: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 QLite core. The
f580: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 se optional inte
f590: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 rfaces are provi
f5a0: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 ded.** by some V
f5b0: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 FSes to facilita
f5c0: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 te testing of th
f5d0: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f e VFS code. By o
f5e0: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 verriding .** sy
f5f0: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 stem calls with
f600: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 functions under
f610: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 its control, a t
f620: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a est program can.
f630: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c ** simulate faul
f640: 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e ts and error con
f650: 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 ditions that wou
f660: 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 ld otherwise be
f670: 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 difficult.** or
f680: 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e impossible to in
f690: 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f duce. The set o
f6a0: 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 f system calls t
f6b0: 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 hat can be overr
f6c0: 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 idden.** varies
f6d0: 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 from one VFS to
f6e0: 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f another, and fro
f6f0: 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 m one version of
f700: 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f the same VFS to
f710: 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 the.** next. A
f720: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
f730: 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 use these inter
f740: 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 faces must be pr
f750: 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a epared for any.*
f760: 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 * or all of thes
f770: 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 e interfaces to
f780: 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 be NULL or for t
f790: 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f heir behavior to
f7a0: 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 change.** from
f7b0: 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 one release to t
f7c0: 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 he next. Applic
f7d0: 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 ations must not
f7e0: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 attempt to acces
f7f0: 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 s.** any of thes
f800: 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 e methods if the
f810: 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 iVersion of the
f820: 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 VFS is less tha
f830: 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 n 3..*/.typedef
f840: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
f850: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a fs sqlite3_vfs;.
f860: 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 typedef void (*s
f870: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 qlite3_syscall_p
f880: 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 tr)(void);.struc
f890: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a t sqlite3_vfs {.
f8a0: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 int iVersion;
f8b0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 /* St
f8c0: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 ructure version
f8d0: 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c number (currentl
f8e0: 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a y 3) */. int sz
f8f0: 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 OsFile;
f900: 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 /* Size of su
f910: 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 bclassed sqlite3
f920: 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d _file */. int m
f930: 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 xPathname;
f940: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 /* Maximum f
f950: 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e ile pathname len
f960: 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 gth */. sqlite3
f970: 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 _vfs *pNext;
f980: 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 /* Next regist
f990: 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f ered VFS */. co
f9a0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b nst char *zName;
f9b0: 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f /* Name o
f9c0: 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 f this virtual f
f9d0: 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 ile system */.
f9e0: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 void *pAppData;
f9f0: 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e /* Poin
fa00: 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 ter to applicati
fa10: 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 on-specific data
fa20: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 */. int (*xOpe
fa30: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c n)(sqlite3_vfs*,
fa40: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
fa50: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 me, sqlite3_file
fa60: 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 *,.
fa70: 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 int flags, int
fa80: 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 *pOutFlags);.
fa90: 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 int (*xDelete)(s
faa0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
fab0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
fac0: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 int syncDir);.
fad0: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 int (*xAccess)(s
fae0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
faf0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
fb00: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a int flags, int *
fb10: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 pResOut);. int
fb20: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 (*xFullPathname)
fb30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
fb40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
fb50: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 , int nOut, char
fb60: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 *zOut);. void
fb70: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 *(*xDlOpen)(sqli
fb80: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
fb90: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 char *zFilename)
fba0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 ;. void (*xDlEr
fbb0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ror)(sqlite3_vfs
fbc0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 *, int nByte, ch
fbd0: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 ar *zErrMsg);.
fbe0: 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 void (*(*xDlSym)
fbf0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f (sqlite3_vfs*,vo
fc00: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 id*, const char
fc10: 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 *zSymbol))(void)
fc20: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c ;. void (*xDlCl
fc30: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ose)(sqlite3_vfs
fc40: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 *, void*);. int
fc50: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 (*xRandomness)(
fc60: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
fc70: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a t nByte, char *z
fc80: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 Out);. int (*xS
fc90: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 leep)(sqlite3_vf
fca0: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 s*, int microsec
fcb0: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 onds);. int (*x
fcc0: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c CurrentTime)(sql
fcd0: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c ite3_vfs*, doubl
fce0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 e*);. int (*xGe
fcf0: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 tLastError)(sqli
fd00: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 te3_vfs*, int, c
fd10: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a har *);. /*. *
fd20: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 * The methods ab
fd30: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 ove are in versi
fd40: 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 on 1 of the sqli
fd50: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 te_vfs object.
fd60: 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 ** definition.
fd70: 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f Those that follo
fd80: 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 w are added in v
fd90: 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 ersion 2 or late
fda0: 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 r. */. int (*x
fdb0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 CurrentTimeInt64
fdc0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
fdd0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b sqlite3_int64*);
fde0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d . /*. ** The m
fdf0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
fe00: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 in versions 1 a
fe10: 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 nd 2 of the sqli
fe20: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 te_vfs object..
fe30: 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 ** Those below
fe40: 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 are for version
fe50: 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 3 and greater..
fe60: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 */. int (*xSet
fe70: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 SystemCall)(sqli
fe80: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
fe90: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c char *zName, sql
fea0: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 ite3_syscall_ptr
feb0: 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 );. sqlite3_sys
fec0: 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 call_ptr (*xGetS
fed0: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 ystemCall)(sqlit
fee0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
fef0: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 har *zName);. c
ff00: 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 onst char *(*xNe
ff10: 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 xtSystemCall)(sq
ff20: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
ff30: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a t char *zName);.
ff40: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 /*. ** The me
ff50: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
ff60: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 in versions 1 th
ff70: 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 rough 3 of the s
ff80: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 qlite_vfs object
ff90: 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 .. ** New field
ffa0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 s may be appende
ffb0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 d in future vers
ffc0: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 ions. The iVers
ffd0: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 ion. ** value w
ffe0: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 ill increment wh
fff0: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 enever this happ
10000 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f ens. . */.};../
10010 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
10020 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 lags for the xAc
10030 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a cess VFS method.
10040 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 **.** These inte
10050 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 ger constants ca
10060 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 n be used as the
10070 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
10080 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 to.** the xAcce
10090 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 ss method of an
100a0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
100b0 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 ject. They dete
100c0 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 rmine.** what ki
100d0 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e nd of permission
100e0 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 s the xAccess me
100f0 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 thod is looking
10100 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c for..** With SQL
10110 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 ITE_ACCESS_EXIST
10120 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d S, the xAccess m
10130 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 ethod.** simply
10140 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 checks whether t
10150 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a he file exists..
10160 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
10170 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c CCESS_READWRITE,
10180 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
10190 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 hod.** checks wh
101a0 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 ether the named
101b0 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 directory is bot
101c0 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 h readable and w
101d0 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f ritable.** (in o
101e0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 ther words, if f
101f0 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 iles can be adde
10200 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 d, removed, and
10210 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a renamed within.*
10220 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 * the directory)
10230 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f ..** The SQLITE_
10240 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
10250 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 constant is cur
10260 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 rently used only
10270 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 by the.** [temp
10280 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 _store_directory
10290 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 pragma], though
102a0 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e this could chan
102b0 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a ge in a future.*
102c0 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c * release of SQL
102d0 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c ite..** With SQL
102e0 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c ITE_ACCESS_READ,
102f0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
10300 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 hod.** checks wh
10310 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 ether the file i
10320 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 s readable. The
10330 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
10340 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a EAD constant is.
10350 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 ** currently unu
10360 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d sed, though it m
10370 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 ight be used in
10380 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 a future release
10390 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a of.** SQLite..*
103a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
103b0 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 _ACCESS_EXISTS
103c0 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
103d0 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 TE_ACCESS_READWR
103e0 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 ITE 1 /* Used
103f0 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 by PRAGMA temp_s
10400 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a tore_directory *
10410 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
10420 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 _ACCESS_READ
10430 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2 /* Unused
10440 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
10450 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 EF: Flags for th
10460 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d e xShmLock VFS m
10470 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ethod.**.** Thes
10480 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
10490 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 nts define the v
104a0 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f arious locking o
104b0 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c perations.** all
104c0 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d owed by the xShm
104d0 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b Lock method of [
104e0 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
104f0 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c ds]. The.** fol
10500 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f lowing are the o
10510 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e nly legal combin
10520 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 ations of flags
10530 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f to the.** xShmLo
10540 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a ck method:.**.**
10550 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 <ul>.** <li> S
10560 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c QLITE_SHM_LOCK |
10570 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 SQLITE_SHM_SHAR
10580 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 ED.** <li> SQLI
10590 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 TE_SHM_LOCK | SQ
105a0 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 LITE_SHM_EXCLUSI
105b0 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 VE.** <li> SQLI
105c0 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 TE_SHM_UNLOCK |
105d0 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 SQLITE_SHM_SHARE
105e0 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 D.** <li> SQLIT
105f0 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 E_SHM_UNLOCK | S
10600 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 QLITE_SHM_EXCLUS
10610 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a IVE.** </ul>.**.
10620 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e ** When unlockin
10630 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 g, the same SHAR
10640 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 ED or EXCLUSIVE
10650 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 flag must be sup
10660 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 plied as.** was
10670 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 given on the cor
10680 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e responding lock.
10690 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 .**.** The xSh
106a0 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e mLock method can
106b0 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 transition betw
106c0 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 een unlocked and
106d0 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 SHARED or.** be
106e0 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 tween unlocked a
106f0 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 nd EXCLUSIVE. I
10700 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 t cannot transit
10710 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 ion between SHAR
10720 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 ED.** and EXCLUS
10730 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 IVE..*/.#define
10740 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 SQLITE_SHM_UNLOC
10750 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e K 1.#defin
10760 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 e SQLITE_SHM_LOC
10770 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 K 2.#def
10780 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 ine SQLITE_SHM_S
10790 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 HARED 4.#d
107a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d efine SQLITE_SHM
107b0 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a _EXCLUSIVE 8.
107c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
107d0 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 Maximum xShmLoc
107e0 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 k index.**.** Th
107f0 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f e xShmLock metho
10800 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f d on [sqlite3_io
10810 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 _methods] may us
10820 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 e values.** betw
10830 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 een 0 and this u
10840 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 pper bound as it
10850 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d s "offset" argum
10860 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 ent..** The SQLi
10870 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 te core will nev
10880 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 er attempt to ac
10890 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 quire or release
108a0 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 a.** lock outsi
108b0 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 de of this range
108c0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
108d0 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 TE_SHM_NLOCK
108e0 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 8.../*.** CA
108f0 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 PI3REF: Initiali
10900 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 ze The SQLite Li
10910 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 brary.**.** ^The
10920 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
10930 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e ize() routine in
10940 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a itializes the.**
10950 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e SQLite library.
10960 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 ^The sqlite3_s
10970 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e hutdown() routin
10980 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 e.** deallocates
10990 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 any resources t
109a0 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 hat were allocat
109b0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ed by sqlite3_in
109c0 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 itialize()..** T
109d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
109e0 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 e designed to ai
109f0 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 d in process ini
10a00 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a tialization and.
10a10 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 ** shutdown on e
10a20 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e mbedded systems.
10a30 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 Workstation ap
10a40 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 plications using
10a50 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 .** SQLite norma
10a60 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 lly do not need
10a70 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 to invoke either
10a80 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
10a90 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c es..**.** A call
10aa0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 to sqlite3_init
10ab0 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 ialize() is an "
10ac0 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 effective" call
10ad0 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 if it is.** the
10ae0 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 first time sqlit
10af0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
10b00 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e is invoked durin
10b10 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f g the lifetime o
10b20 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 f.** the process
10b30 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 , or if it is th
10b40 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c e first time sql
10b50 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
10b60 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 ) is invoked.**
10b70 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c following a call
10b80 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 to sqlite3_shut
10b90 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 down(). ^(Only
10ba0 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c an effective cal
10bb0 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f l.** of sqlite3_
10bc0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 initialize() doe
10bd0 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 s any initializa
10be0 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 tion. All other
10bf0 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 calls.** are ha
10c00 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e rmless no-ops.)^
10c10 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f .**.** A call to
10c20 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
10c30 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 n() is an "effec
10c40 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 tive" call if it
10c50 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a is the first.**
10c60 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
10c70 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 _shutdown() sinc
10c80 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 e the last sqlit
10c90 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e e3_initialize().
10ca0 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 ^(Only.** an e
10cb0 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f ffective call to
10cc0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
10cd0 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 n() does any dei
10ce0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a nitialization..*
10cf0 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 * All other vali
10d00 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 d calls to sqlit
10d10 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 e3_shutdown() ar
10d20 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 e harmless no-op
10d30 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 s.)^.**.** The s
10d40 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
10d50 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 e() interface is
10d60 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 threadsafe, but
10d70 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
10d80 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 n().** is not.
10d90 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 The sqlite3_shut
10da0 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 down() interface
10db0 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 must only be ca
10dc0 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 lled from a.** s
10dd0 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 ingle thread. A
10de0 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 ll open [databas
10df0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d e connections] m
10e00 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e ust be closed an
10e10 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 d all.** other S
10e20 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 QLite resources
10e30 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 must be dealloca
10e40 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 ted prior to inv
10e50 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 oking.** sqlite3
10e60 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a _shutdown()..**.
10e70 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 ** Among other t
10e80 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f hings, ^sqlite3_
10e90 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c initialize() wil
10ea0 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 l invoke.** sqli
10eb0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 te3_os_init().
10ec0 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 Similarly, ^sqli
10ed0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a te3_shutdown().*
10ee0 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 * will invoke sq
10ef0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a lite3_os_end()..
10f00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
10f10 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
10f20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
10f30 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 [SQLITE_OK] on s
10f40 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 uccess..** ^If f
10f50 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 or some reason,
10f60 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
10f70 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 ze() is unable t
10f80 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 o initialize.**
10f90 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 the library (per
10fa0 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c haps it is unabl
10fb0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 e to allocate a
10fc0 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 needed resource
10fd0 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 such.** as a mut
10fe0 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 ex) it returns a
10ff0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f n [error code] o
11000 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
11010 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 E_OK]..**.** ^Th
11020 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
11030 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 lize() routine i
11040 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 s called interna
11050 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 lly by many othe
11060 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 r.** SQLite inte
11070 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 rfaces so that a
11080 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 n application us
11090 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e ually does not n
110a0 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 eed to.** invoke
110b0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
110c0 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 ize() directly.
110d0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 For example, [s
110e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a qlite3_open()].*
110f0 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f * calls sqlite3_
11100 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 initialize() so
11110 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
11120 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d ry will be autom
11130 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 atically.** init
11140 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 ialized when [sq
11150 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 lite3_open()] is
11160 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 called if it ha
11170 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c s not be initial
11180 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e ized.** already.
11190 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 ^However, if S
111a0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
111b0 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 d with the [SQLI
111c0 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 TE_OMIT_AUTOINIT
111d0 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d ].** compile-tim
111e0 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 e option, then t
111f0 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c he automatic cal
11200 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e ls to sqlite3_in
11210 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 itialize().** ar
11220 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 e omitted and th
11230 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
11240 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f st call sqlite3_
11250 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 initialize() dir
11260 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 ectly.** prior t
11270 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 o using any othe
11280 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
11290 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d ce. For maximum
112a0 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a portability,.**
112b0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 it is recommend
112c0 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 ed that applicat
112d0 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f ions always invo
112e0 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ke sqlite3_initi
112f0 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 alize().** direc
11300 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 tly prior to usi
11310 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c ng any other SQL
11320 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ite interface.
11330 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a Future releases.
11340 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 ** of SQLite may
11350 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 require this.
11360 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
11370 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 the behavior exh
11380 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 ibited.** when S
11390 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
113a0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f d with [SQLITE_O
113b0 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 MIT_AUTOINIT] mi
113c0 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a ght become the.*
113d0 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 * default behavi
113e0 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 or in some futur
113f0 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c e release of SQL
11400 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ite..**.** The s
11410 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
11420 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 routine does op
11430 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 erating-system s
11440 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 pecific.** initi
11450 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 alization of the
11460 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e SQLite library.
11470 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 The sqlite3_os
11480 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e _end().** routin
11490 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 e undoes the eff
114a0 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f ect of sqlite3_o
114b0 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 s_init(). Typic
114c0 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 al tasks.** perf
114d0 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 ormed by these r
114e0 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 outines include
114f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 allocation or de
11500 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 allocation.** of
11510 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 static resource
11520 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f s, initializatio
11530 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 n of global vari
11540 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e ables,.** settin
11550 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b g up a default [
11560 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 sqlite3_vfs] mod
11570 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 ule, or setting
11580 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 up.** a default
11590 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 configuration us
115a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e ing [sqlite3_con
115b0 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 fig()]..**.** Th
115c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
115d0 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b ould never invok
115e0 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 e either sqlite3
115f0 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 _os_init().** or
11600 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
11610 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 ) directly. The
11620 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
11630 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a uld only invoke.
11640 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ** sqlite3_initi
11650 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 alize() and sqli
11660 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 te3_shutdown().
11670 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
11680 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 init().** interf
11690 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 ace is called au
116a0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 tomatically by s
116b0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
116c0 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 e() and.** sqlit
116d0 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 e3_os_end() is c
116e0 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 alled by sqlite3
116f0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 _shutdown(). Ap
11700 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 propriate.** imp
11710 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 lementations for
11720 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
11730 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
11740 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 s_end().** are b
11750 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 uilt into SQLite
11760 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 when it is comp
11770 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 iled for Unix, W
11780 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e indows, or OS/2.
11790 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d .** When [custom
117a0 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 builds | built
117b0 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f for other platfo
117c0 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 rms].** (using t
117d0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 he [SQLITE_OS_OT
117e0 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 HER=1] compile-t
117f0 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 ime.** option) t
11800 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
11810 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 ust supply a sui
11820 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 table implementa
11830 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 tion for.** sqli
11840 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e te3_os_init() an
11850 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 d sqlite3_os_end
11860 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 (). An applicat
11870 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 ion-supplied.**
11880 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
11890 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 f sqlite3_os_ini
118a0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f t() or sqlite3_o
118b0 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 s_end().** must
118c0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
118d0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e K] on success an
118e0 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 d some other [er
118f0 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a ror code] upon.*
11900 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e * failure..*/.in
11910 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 t sqlite3_initia
11920 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 lize(void);.int
11930 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
11940 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 (void);.int sqli
11950 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 te3_os_init(void
11960 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f );.int sqlite3_o
11970 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a s_end(void);../*
11980 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
11990 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 nfiguring The SQ
119a0 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a Lite Library.**.
119b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
119c0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
119d0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b e is used to mak
119e0 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 e global configu
119f0 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 ration.** change
11a00 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f s to SQLite in o
11a10 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c rder to tune SQL
11a20 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 ite to the speci
11a30 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 fic needs of.**
11a40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e the application.
11a50 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f The default co
11a60 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 nfiguration is r
11a70 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d ecommended for m
11a80 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 ost.** applicati
11a90 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 ons and so this
11aa0 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c routine is usual
11ab0 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 ly not necessary
11ac0 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 . It is.** prov
11ad0 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 ided to support
11ae0 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e rare application
11af0 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e s with unusual n
11b00 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 eeds..**.** <b>T
11b10 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 he sqlite3_confi
11b20 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 g() interface is
11b30 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e not threadsafe.
11b40 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
11b50 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 .** must ensure
11b60 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 that no other SQ
11b70 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 Lite interfaces
11b80 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f are invoked by o
11b90 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 ther.** threads
11ba0 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f while sqlite3_co
11bb0 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e nfig() is runnin
11bc0 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 g.</b>.**.** The
11bd0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
11be0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d ) interface.** m
11bf0 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b ay only be invok
11c00 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 ed prior to libr
11c10 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 ary initializati
11c20 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c on using.** [sql
11c30 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
11c40 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 )] or after shut
11c50 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 down by [sqlite3
11c60 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a _shutdown()]..**
11c70 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e ^If sqlite3_con
11c80 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 fig() is called
11c90 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 after [sqlite3_i
11ca0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 nitialize()] and
11cb0 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 before.** [sqli
11cc0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 te3_shutdown()]
11cd0 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 then it will ret
11ce0 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 urn SQLITE_MISUS
11cf0 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 E..** Note, howe
11d00 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 ver, that ^sqlit
11d10 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 e3_config() can
11d20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 be called as par
11d30 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c t of the.** impl
11d40 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e ementation of an
11d50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
11d60 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 ined [sqlite3_os
11d70 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _init()]..**.**
11d80 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
11d90 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f nt to sqlite3_co
11da0 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 nfig() is an int
11db0 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 eger.** [configu
11dc0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 ration option] t
11dd0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a hat determines.*
11de0 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 * what property
11df0 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 of SQLite is to
11e00 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 be configured.
11e10 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d Subsequent argum
11e20 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 ents.** vary dep
11e30 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 ending on the [c
11e40 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
11e50 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 ion].** in the f
11e60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a irst argument..*
11e70 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e *.** ^When a con
11e80 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
11e90 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 n is set, sqlite
11ea0 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 3_config() retur
11eb0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a ns [SQLITE_OK]..
11ec0 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f ** ^If the optio
11ed0 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 n is unknown or
11ee0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 SQLite is unable
11ef0 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 to set the opti
11f00 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 on.** then this
11f10 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
11f20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f a non-zero [erro
11f30 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 r code]..*/.int
11f40 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 sqlite3_config(i
11f50 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a nt, ...);../*.**
11f60 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 CAPI3REF: Confi
11f70 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f gure database co
11f80 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 nnections.** MET
11f90 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
11fa0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 ** The sqlite3_d
11fb0 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 b_config() inter
11fc0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 face is used to
11fd0 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 make configurati
11fe0 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f on.** changes to
11ff0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
12000 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 nection]. The i
12010 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 nterface is simi
12020 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 lar to.** [sqlit
12030 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 e3_config()] exc
12040 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 ept that the cha
12050 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 nges apply to a
12060 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 single.** [datab
12070 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
12080 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 (specified in th
12090 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
120a0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 )..**.** The sec
120b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
120c0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
120d0 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 g(D,V,...) is t
120e0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 he.** [SQLITE_DB
120f0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
12100 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e | configuration
12110 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 verb] - an inte
12120 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 ger code .** tha
12130 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 t indicates what
12140 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b aspect of the [
12150 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
12160 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f ion] is being co
12170 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 nfigured..** Sub
12180 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 sequent argument
12190 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 s vary depending
121a0 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 on the configur
121b0 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a ation verb..**.*
121c0 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 * ^Calls to sqli
121d0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 te3_db_config()
121e0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b return SQLITE_OK
121f0 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a if and only if.
12200 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 ** the call is c
12210 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 onsidered succes
12220 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c sful..*/.int sql
12230 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 ite3_db_config(s
12240 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c qlite3*, int op,
12250 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ...);../*.** CA
12260 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
12270 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e llocation Routin
12280 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 es.**.** An inst
12290 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
122a0 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 ect defines the
122b0 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 interface betwee
122c0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 n SQLite.** and
122d0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 low-level memory
122e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
122f0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ines..**.** This
12300 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 object is used
12310 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 in only one plac
12320 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 e in the SQLite
12330 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 interface..** A
12340 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
12350 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
12360 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 bject is the arg
12370 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c ument to.** [sql
12380 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
12390 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 hen the configur
123a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a ation option is.
123b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
123c0 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 G_MALLOC] or [SQ
123d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
123e0 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 ALLOC]. .** By
123f0 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 creating an inst
12400 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
12410 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 ect.** and passi
12420 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 ng it to [sqlite
12430 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 3_config]([SQLIT
12440 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
12450 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 ).** during conf
12460 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 iguration, an ap
12470 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 plication can sp
12480 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 ecify an alterna
12490 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 tive.** memory a
124a0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
124b0 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 tem for SQLite t
124c0 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 o use for all of
124d0 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 its.** dynamic
124e0 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a memory needs..**
124f0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 .** Note that SQ
12500 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 Lite comes with
12510 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 several [built-i
12520 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
12530 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 ors].** that are
12540 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 perfectly adequ
12550 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 ate for the over
12560 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 whelming majorit
12570 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e y of application
12580 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 s.** and that th
12590 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c is object is onl
125a0 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 y useful to a ti
125b0 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 ny minority of a
125c0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 pplications.** w
125d0 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 ith specialized
125e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
125f0 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 n requirements.
12600 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a This object is.
12610 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 ** also used dur
12620 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 ing testing of S
12630 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 QLite in order t
12640 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 o specify an alt
12650 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f ernative.** memo
12660 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 ry allocator tha
12670 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f t simulates memo
12680 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 ry out-of-memory
12690 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a conditions in.*
126a0 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 * order to verif
126b0 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 y that SQLite re
126c0 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c covers gracefull
126d0 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 y from such.** c
126e0 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a onditions..**.**
126f0 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 The xMalloc, xR
12700 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 ealloc, and xFre
12710 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 e methods must w
12720 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 ork like the.**
12730 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f malloc(), reallo
12740 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 c() and free() f
12750 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 unctions from th
12760 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 e standard C lib
12770 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 rary..** ^SQLite
12780 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
12790 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
127a0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c ment to.** xReal
127b0 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 loc is always a
127c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
127d0 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 y a prior call t
127e0 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a o xRoundup..**.*
127f0 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 * xSize should r
12800 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 eturn the alloca
12810 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 ted size of a me
12820 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a mory allocation.
12830 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 ** previously ob
12840 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c tained from xMal
12850 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e loc or xRealloc.
12860 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 The allocated
12870 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 size.** is alway
12880 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 s at least as bi
12890 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 g as the request
128a0 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 ed size but may
128b0 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a be larger..**.**
128c0 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 The xRoundup me
128d0 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 thod returns wha
128e0 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 t would be the a
128f0 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 llocated size of
12900 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c .** a memory all
12910 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 ocation given a
12920 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 particular reque
12930 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 sted size. Most
12940 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
12950 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d ators round up m
12960 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
12970 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 s at least to th
12980 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a e next multiple.
12990 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 ** of 8. Some a
129a0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 llocators round
129b0 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d up to a larger m
129c0 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 ultiple or to a
129d0 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 power of 2..** E
129e0 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f very memory allo
129f0 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 cation request c
12a00 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 oming in through
12a10 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
12a20 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 ()].** or [sqlit
12a30 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 e3_realloc()] fi
12a40 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 rst calls xRound
12a50 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 up. If xRoundup
12a60 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 returns 0, .**
12a70 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 that causes the
12a80 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 corresponding me
12a90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
12aa0 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 to fail..**.** T
12ab0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 he xInit method
12ac0 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 initializes the
12ad0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
12ae0 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a . For example,.
12af0 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f ** it might allo
12b00 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 cate any require
12b10 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 mutexes or init
12b20 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 ialize internal
12b30 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 data.** structur
12b40 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f es. The xShutdo
12b50 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 wn method is inv
12b60 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 oked (indirectly
12b70 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ) by.** [sqlite3
12b80 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 _shutdown()] and
12b90 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 should dealloca
12ba0 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 te any resources
12bb0 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 acquired.** by
12bc0 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 xInit. The pApp
12bd0 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 Data pointer is
12be0 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 used as the only
12bf0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
12c00 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 xInit and xShut
12c10 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 down..**.** SQLi
12c20 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 te holds the [SQ
12c30 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
12c40 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 C_MASTER] mutex
12c50 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a when it invokes.
12c60 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 ** the xInit met
12c70 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 hod, so the xIni
12c80 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f t method need no
12c90 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e t be threadsafe.
12ca0 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f The.** xShutdo
12cb0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c wn method is onl
12cc0 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 y called from [s
12cd0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
12ce0 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a )] so it does.**
12cf0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 not need to be
12d00 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 threadsafe eithe
12d10 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 r. For all othe
12d20 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 r methods, SQLit
12d30 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b e.** holds the [
12d40 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
12d50 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 TIC_MEM] mutex a
12d60 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a s long as the.**
12d70 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
12d80 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 MEMSTATUS] confi
12d90 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
12da0 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 is turned on (wh
12db0 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 ich.** it is by
12dc0 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 default) and so
12dd0 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 the methods are
12de0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 automatically se
12df0 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 rialized..** How
12e00 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 ever, if [SQLITE
12e10 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
12e20 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 S] is disabled,
12e30 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a then the other.*
12e40 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 * methods must b
12e50 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 e threadsafe or
12e60 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 else make their
12e70 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 own arrangements
12e80 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a for.** serializ
12e90 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c ation..**.** SQL
12ea0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 ite will never i
12eb0 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f nvoke xInit() mo
12ec0 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 re than once wit
12ed0 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e hout an interven
12ee0 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 ing.** call to x
12ef0 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 Shutdown()..*/.t
12f00 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
12f10 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
12f20 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 s sqlite3_mem_me
12f30 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 thods;.struct sq
12f40 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
12f50 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d s {. void *(*xM
12f60 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 alloc)(int);
12f70 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 /* Memory a
12f80 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 llocation functi
12f90 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 on */. void (*x
12fa0 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 Free)(void*);
12fb0 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 /* Free a
12fc0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
12fd0 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 n */. void *(*x
12fe0 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 Realloc)(void*,i
12ff0 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 nt); /* Resize
13000 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f an allocation */
13010 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 . int (*xSize)(
13020 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 void*);
13030 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 /* Return the
13040 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 size of an alloc
13050 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 ation */. int (
13060 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b *xRoundup)(int);
13070 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 /* Rou
13080 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 nd up request si
13090 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e ze to allocation
130a0 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 size */. int (
130b0 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 *xInit)(void*);
130c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 /* Ini
130d0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f tialize the memo
130e0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a ry allocator */.
130f0 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f void (*xShutdo
13100 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 wn)(void*);
13110 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 /* Deinitialize
13120 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
13130 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 cator */. void
13140 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 *pAppData;
13150 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 /* Arg
13160 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 ument to xInit()
13170 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 and xShutdown()
13180 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
13190 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 PI3REF: Configur
131a0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a ation Options.**
131b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 KEYWORDS: {conf
131c0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
131d0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f }.**.** These co
131e0 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 nstants are the
131f0 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 available intege
13200 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 r configuration
13210 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 options that.**
13220 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 can be passed as
13230 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
13240 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ent to the [sqli
13250 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e te3_config()] in
13260 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e terface..**.** N
13270 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ew configuration
13280 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 options may be
13290 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
132a0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
132b0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 te..** Existing
132c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
132d0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 tions might be d
132e0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 iscontinued. Ap
132f0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 plications.** sh
13300 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 ould check the r
13310 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 eturn code from
13320 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
13330 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 )] to make sure
13340 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c that.** the call
13350 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 worked. The [s
13360 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
13370 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 interface will
13380 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d return a.** non-
13390 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
133a0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e ] if a discontin
133b0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 ued or unsupport
133c0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ed configuration
133d0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e option.** is in
133e0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c voked..**.** <dl
133f0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f >.** [[SQLITE_CO
13400 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
13410 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 D]] <dt>SQLITE_C
13420 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
13430 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 AD</dt>.** <dd>T
13440 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 here are no argu
13450 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 ments to this op
13460 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 tion. ^This opt
13470 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 ion sets the.**
13480 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
13490 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 to Single-threa
134a0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 d. In other wor
134b0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a ds, it disables.
134c0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 ** all mutexing
134d0 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 and puts SQLite
134e0 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 into a mode wher
134f0 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 e it can only be
13500 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 used.** by a si
13510 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e ngle thread. ^
13520 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
13530 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
13540 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
13550 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
13560 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
13570 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
13580 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f then.** it is no
13590 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 t possible to ch
135a0 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 ange the [thread
135b0 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 ing mode] from i
135c0 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 ts default.** va
135d0 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 lue of Single-th
135e0 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c read and so [sql
135f0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
13600 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b ill return .** [
13610 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
13620 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 called with the
13630 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
13640 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 INGLETHREAD.** c
13650 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
13660 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ion.</dd>.**.**
13670 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
13680 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 MULTITHREAD]] <d
13690 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
136a0 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e MULTITHREAD</dt>
136b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
136c0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
136d0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
136e0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 ^This option set
136f0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 s the.** [thread
13700 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c ing mode] to Mul
13710 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f ti-thread. In o
13720 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 ther words, it d
13730 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 isables.** mutex
13740 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 ing on [database
13750 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 connection] and
13760 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
13770 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a ment] objects..*
13780 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
13790 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 n is responsible
137a0 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 for serializing
137b0 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 access to.** [d
137c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
137d0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ons] and [prepar
137e0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 ed statements].
137f0 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 But other mutex
13800 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 es.** are enable
13810 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 d so that SQLite
13820 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f will be safe to
13830 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d use in a multi-
13840 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 threaded.** envi
13850 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 ronment as long
13860 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 as no two thread
13870 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 s attempt to use
13880 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 the same.** [da
13890 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
138a0 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 n] at the same t
138b0 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 ime. ^If SQLite
138c0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
138d0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
138e0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
138f0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
13900 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
13910 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 option then.** i
13920 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c t is not possibl
13930 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c e to set the Mul
13940 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 ti-thread [threa
13950 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a ding mode] and.*
13960 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
13970 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e g()] will return
13980 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
13990 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 if called with t
139a0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e he.** SQLITE_CON
139b0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 FIG_MULTITHREAD
139c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
139d0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tion.</dd>.**.**
139e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
139f0 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 _SERIALIZED]] <d
13a00 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
13a10 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a SERIALIZED</dt>.
13a20 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 ** <dd>There are
13a30 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f no arguments to
13a40 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e this option. ^
13a50 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 This option sets
13a60 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 the.** [threadi
13a70 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 ng mode] to Seri
13a80 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 alized. In other
13a90 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 words, this opt
13aa0 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 ion enables.** a
13ab0 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 ll mutexes inclu
13ac0 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 ding the recursi
13ad0 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e ve.** mutexes on
13ae0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
13af0 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 ction] and [prep
13b00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
13b10 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 objects..** In t
13b20 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 his mode (which
13b30 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 is the default w
13b40 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f hen SQLite is co
13b50 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b mpiled with.** [
13b60 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
13b70 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 E=1]) the SQLite
13b80 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 library will it
13b90 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 self serialize a
13ba0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 ccess.** to [dat
13bb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
13bc0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 s] and [prepared
13bd0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 statements] so
13be0 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c that the.** appl
13bf0 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 ication is free
13c00 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 to use the same
13c10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
13c20 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 tion] or the.**
13c30 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 same [prepared s
13c40 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 tatement] in dif
13c50 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 ferent threads a
13c60 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e t the same time.
13c70 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 .** ^If SQLite i
13c80 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
13c90 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
13ca0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
13cb0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
13cc0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
13cd0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 tion then.** it
13ce0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 is not possible
13cf0 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61 to set the Seria
13d00 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
13d10 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 mode] and.** [s
13d20 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
13d30 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
13d40 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 LITE_ERROR] if c
13d50 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a alled with the.*
13d60 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f * SQLITE_CONFIG_
13d70 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 SERIALIZED confi
13d80 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e guration option.
13d90 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
13da0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
13db0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f OC]] <dt>SQLITE_
13dc0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 CONFIG_MALLOC</d
13dd0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 t>.** <dd> ^(The
13de0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
13df0 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b ALLOC option tak
13e00 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
13e10 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a ment which is .*
13e20 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * a pointer to a
13e30 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
13e40 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d e [sqlite3_mem_m
13e50 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
13e60 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 e..** The argume
13e70 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 nt specifies.**
13e80 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d alternative low-
13e90 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c level memory all
13ea0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
13eb0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 to be used in p
13ec0 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d lace of.** the m
13ed0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
13ee0 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 routines built
13ef0 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e into SQLite.)^ ^
13f00 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 SQLite makes.**
13f10 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
13f20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 copy of the cont
13f30 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 ent of the [sqli
13f40 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
13f50 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 structure.** be
13f60 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 fore the [sqlite
13f70 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 3_config()] call
13f80 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a returns.</dd>.*
13f90 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
13fa0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d NFIG_GETMALLOC]]
13fb0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
13fc0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 IG_GETMALLOC</dt
13fd0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 >.** <dd> ^(The
13fe0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
13ff0 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 TMALLOC option t
14000 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
14010 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 gument which.**
14020 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
14030 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
14040 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f he [sqlite3_mem_
14050 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
14060 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 re..** The [sqli
14070 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
14080 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 .** structure is
14090 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 filled with the
140a0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e currently defin
140b0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ed memory alloca
140c0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e tion routines.)^
140d0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 .** This option
140e0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
140f0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 verload the defa
14100 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ult memory alloc
14110 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 ation.** routine
14120 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 s with a wrapper
14130 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e that simulation
14140 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 s memory allocat
14150 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a ion failure or.*
14160 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 * tracks memory
14170 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 usage, for examp
14180 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 le. </dd>.**.**
14190 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
141a0 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c SMALL_MALLOC]] <
141b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
141c0 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 _SMALL_MALLOC</d
141d0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 t>.** <dd> ^The
141e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d SQLITE_CONFIG_SM
141f0 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f ALL_MALLOC optio
14200 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 n takes single a
14210 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 rgument of.** ty
14220 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 pe int, interpre
14230 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e ted as a boolean
14240 2c 20 77 68 69 63 68 20 69 66 20 74 72 75 65 20 , which if true
14250 70 72 6f 76 69 64 65 73 20 61 20 68 69 6e 74 20 provides a hint
14260 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68 61 to.** SQLite tha
14270 74 20 69 74 20 73 68 6f 75 6c 64 20 61 76 6f 69 t it should avoi
14280 64 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 d large memory a
14290 6c 6c 6f 63 61 74 69 6f 6e 73 20 69 66 20 70 6f llocations if po
142a0 73 73 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 ssible..** SQLit
142b0 65 20 77 69 6c 6c 20 72 75 6e 20 66 61 73 74 65 e will run faste
142c0 72 20 69 66 20 69 74 20 69 73 20 66 72 65 65 20 r if it is free
142d0 74 6f 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65 to make large me
142e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 mory allocations
142f0 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61 70 ,.** but some ap
14300 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 plication might
14310 70 72 65 66 65 72 20 74 6f 20 72 75 6e 20 73 6c prefer to run sl
14320 6f 77 65 72 20 69 6e 20 65 78 63 68 61 6e 67 65 ower in exchange
14330 20 66 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65 for.** guarante
14340 65 73 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20 es about memory
14350 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68 fragmentation th
14360 61 74 20 61 72 65 20 70 6f 73 73 69 62 6c 65 20 at are possible
14370 69 66 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f if large.** allo
14380 63 61 74 69 6f 6e 73 20 61 72 65 20 61 76 6f 69 cations are avoi
14390 64 65 64 2e 20 20 54 68 69 73 20 68 69 6e 74 20 ded. This hint
143a0 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e is normally off.
143b0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .** </dd>.**.**
143c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
143d0 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e MEMSTATUS]] <dt>
143e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
143f0 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 MSTATUS</dt>.**
14400 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 <dd> ^The SQLITE
14410 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
14420 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 S option takes s
14430 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f ingle argument o
14440 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 f type int,.** i
14450 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
14460 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 boolean, which e
14470 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c nables or disabl
14480 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f es the collectio
14490 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 n of.** memory a
144a0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 llocation statis
144b0 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d tics. ^(When mem
144c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 ory allocation s
144d0 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a tatistics are.**
144e0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 disabled, the f
144f0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 ollowing SQLite
14500 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d interfaces becom
14510 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 e non-operationa
14520 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 l:.** <ul>.**
14530 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
14540 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a memory_used()].*
14550 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 * <li> [sqlite
14560 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
14570 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 er()].** <li>
14580 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 [sqlite3_soft_he
14590 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a ap_limit64()].**
145a0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
145b0 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 _status64()].**
145c0 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 </ul>)^.** ^Me
145d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
145e0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 statistics are e
145f0 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c nabled by defaul
14600 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 t unless SQLite
14610 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 is.** compiled w
14620 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 ith [SQLITE_DEFA
14630 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 ULT_MEMSTATUS]=0
14640 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d in which case m
14650 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
14660 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 ion statistics a
14670 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 re disabled by d
14680 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e efault..** </dd>
14690 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
146a0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d CONFIG_SCRATCH]]
146b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
146c0 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a IG_SCRATCH</dt>.
146d0 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 ** <dd> The SQLI
146e0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
146f0 48 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c H option is no l
14700 6f 6e 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c onger used..** <
14710 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
14720 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
14730 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 ACHE]] <dt>SQLIT
14740 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
14750 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 HE</dt>.** <dd>
14760 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
14770 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 IG_PAGECACHE opt
14780 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
14790 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 memory pool.** t
147a0 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 hat SQLite can u
147b0 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 se for the datab
147c0 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 ase page cache w
147d0 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 ith the default
147e0 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d page.** cache im
147f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a plementation. .
14800 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 ** This configur
14810 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 ation option is
14820 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 a no-op if an ap
14830 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
14840 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 page.** cache i
14850 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
14860 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 loaded using th
14870 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 e [SQLITE_CONFIG
14880 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 _PCACHE2]..** ^T
14890 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
148a0 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 rguments to SQLI
148b0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
148c0 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 CHE: A pointer t
148d0 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 o.** 8-byte alig
148e0 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d ned memory (pMem
148f0 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 ), the size of e
14900 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c ach page cache l
14910 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 ine (sz),.** and
14920 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
14930 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a ache lines (N)..
14940 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 ** The sz argume
14950 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 nt should be the
14960 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 size of the lar
14970 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 gest database pa
14980 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f ge.** (a power o
14990 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 f two between 51
149a0 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 2 and 65536) plu
149b0 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 s some extra byt
149c0 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 es for each.** p
149d0 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 age header. ^Th
149e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 e number of extr
149f0 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 a bytes needed b
14a00 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65 y the page heade
14a10 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 r.** can be dete
14a20 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 rmined using [SQ
14a30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
14a40 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 HE_HDRSZ]..** ^I
14a50 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 t is harmless, a
14a60 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 part from the wa
14a70 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 sted memory,.**
14a80 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d for the sz param
14a90 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 eter to be large
14aa0 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 r than necessary
14ab0 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 . The pMem.** a
14ac0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 rgument must be
14ad0 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f either a NULL po
14ae0 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 inter or a point
14af0 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a er to an 8-byte.
14b00 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b ** aligned block
14b10 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 of memory of at
14b20 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 least sz*N byte
14b30 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 s, otherwise.**
14b40 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 subsequent behav
14b50 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
14b60 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 ..** ^When pMem
14b70 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c is not NULL, SQL
14b80 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 ite will strive
14b90 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 to use the memor
14ba0 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f y provided.** to
14bb0 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61 satisfy page ca
14bc0 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 che needs, falli
14bd0 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 ng back to [sqli
14be0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 te3_malloc()] if
14bf0 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 .** a page cache
14c00 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 line is larger
14c10 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 than sz bytes or
14c20 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 if all of the p
14c30 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 Mem buffer.** is
14c40 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e exhausted..** ^
14c50 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 If pMem is NULL
14c60 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 and N is non-zer
14c70 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 o, then each dat
14c80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
14c90 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 .** does an init
14ca0 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 ial bulk allocat
14cb0 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 ion for page cac
14cc0 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f he memory.** fro
14cd0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
14ce0 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 c()] sufficient
14cf0 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 for N cache line
14d00 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 s if N is positi
14d10 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 ve or.** of -102
14d20 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 4*N bytes if N i
14d30 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 s negative, . ^I
14d40 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 f additional.**
14d50 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 page cache memor
14d60 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f y is needed beyo
14d70 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 nd what is provi
14d80 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 ded by the initi
14d90 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e al.** allocation
14da0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f , then SQLite go
14db0 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d es to [sqlite3_m
14dc0 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 alloc()] separat
14dd0 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 ely for each.**
14de0 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 additional cache
14df0 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a line. </dd>.**.
14e00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
14e10 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 IG_HEAP]] <dt>SQ
14e20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
14e30 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
14e40 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
14e50 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 _HEAP option spe
14e60 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
14e70 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a memory buffer .*
14e80 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 * that SQLite wi
14e90 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f ll use for all o
14ea0 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 f its dynamic me
14eb0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
14ec0 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 needs.** beyond
14ed0 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 those provided f
14ee0 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f or by [SQLITE_CO
14ef0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e NFIG_PAGECACHE].
14f00 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f .** ^The SQLITE_
14f10 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 CONFIG_HEAP opti
14f20 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c on is only avail
14f30 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 able if SQLite i
14f40 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 s compiled.** wi
14f50 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 th either [SQLIT
14f60 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 E_ENABLE_MEMSYS3
14f70 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 ] or [SQLITE_ENA
14f80 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 BLE_MEMSYS5] and
14f90 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c returns.** [SQL
14fa0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e ITE_ERROR] if in
14fb0 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e voked otherwise.
14fc0 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 .** ^There are t
14fd0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 hree arguments t
14fe0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f o SQLITE_CONFIG_
14ff0 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 HEAP:.** An 8-by
15000 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 te aligned point
15010 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 er to the memory
15020 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 ,.** the number
15030 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
15040 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 memory buffer, a
15050 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 nd the minimum a
15060 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a llocation size..
15070 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 ** ^If the first
15080 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 pointer (the me
15090 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 mory pointer) is
150a0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 NULL, then SQLi
150b0 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f te reverts.** to
150c0 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 using its defau
150d0 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 lt memory alloca
150e0 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 tor (the system
150f0 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 malloc() impleme
15100 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 ntation),.** und
15110 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 oing any prior i
15120 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 nvocation of [SQ
15130 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
15140 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a OC]. ^If the.**
15150 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 memory pointer
15160 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e is not NULL then
15170 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 the alternative
15180 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
15190 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 ator is engaged
151a0 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 to handle all of
151b0 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 SQLites memory
151c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
151d0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 ..** The first p
151e0 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f ointer (the memo
151f0 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 ry pointer) must
15200 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 be aligned to a
15210 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e n 8-byte.** boun
15220 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 dary or subseque
15230 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 nt behavior of S
15240 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e QLite will be un
15250 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 defined..** The
15260 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 minimum allocati
15270 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 on size is cappe
15280 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 d at 2**12. Reas
15290 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a onable values.**
152a0 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d for the minimum
152b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 allocation size
152c0 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 are 2**5 throug
152d0 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a h 2**8.</dd>.**.
152e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
152f0 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 IG_MUTEX]] <dt>S
15300 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
15310 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 EX</dt>.** <dd>
15320 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^(The SQLITE_CON
15330 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e FIG_MUTEX option
15340 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
15350 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
15360 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 s a.** pointer t
15370 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
15380 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
15390 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 tex_methods] str
153a0 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 ucture..** The a
153b0 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 rgument specifie
153c0 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f s alternative lo
153d0 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f w-level mutex ro
153e0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 utines to be use
153f0 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 d.** in place th
15400 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 e mutex routines
15410 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 built into SQLi
15420 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d te.)^ ^SQLite m
15430 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a akes a copy of.*
15440 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 * the content of
15450 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
15460 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 tex_methods] str
15470 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 ucture before th
15480 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 e call to.** [sq
15490 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
154a0 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c returns. ^If SQL
154b0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
154c0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c with.** the [SQL
154d0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c ITE_THREADSAFE |
154e0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
154f0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 FE=0] compile-ti
15500 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a me option then.*
15510 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 * the entire mut
15520 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 exing subsystem
15530 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 is omitted from
15540 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 the build and he
15550 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 nce calls to.**
15560 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
15570 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 )] with the SQLI
15580 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 TE_CONFIG_MUTEX
15590 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
155a0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 tion will.** ret
155b0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f urn [SQLITE_ERRO
155c0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b R].</dd>.**.** [
155d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 [SQLITE_CONFIG_G
155e0 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 ETMUTEX]] <dt>SQ
155f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
15600 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 UTEX</dt>.** <dd
15610 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 > ^(The SQLITE_C
15620 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f ONFIG_GETMUTEX o
15630 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
15640 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
15650 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e ich.** is a poin
15660 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
15670 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
15680 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
15690 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 ] structure. Th
156a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 e.** [sqlite3_mu
156b0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 tex_methods].**
156c0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c structure is fil
156d0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 led with the cur
156e0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d rently defined m
156f0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e utex routines.)^
15700 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 .** This option
15710 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
15720 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 verload the defa
15730 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 ult mutex alloca
15740 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 tion.** routines
15750 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 with a wrapper
15760 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 used to track mu
15770 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 tex usage for pe
15780 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f rformance.** pro
15790 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e filing or testin
157a0 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 g, for example.
157b0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 ^If SQLite is
157c0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
157d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
157e0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
157f0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
15800 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
15810 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 on then.** the e
15820 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 ntire mutexing s
15830 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 ubsystem is omit
15840 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 ted from the bui
15850 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c ld and hence cal
15860 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ls to.** [sqlite
15870 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 3_config()] with
15880 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 the SQLITE_CONF
15890 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 IG_GETMUTEX conf
158a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
158b0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 will.** return
158c0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c [SQLITE_ERROR].<
158d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
158e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
158f0 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 SIDE]] <dt>SQLIT
15900 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
15910 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 DE</dt>.** <dd>
15920 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^(The SQLITE_CON
15930 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 FIG_LOOKASIDE op
15940 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 tion takes two a
15950 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 rguments that de
15960 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 termine.** the d
15970 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c efault size of l
15980 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
15990 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 on each [databas
159a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a e connection]..*
159b0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
159c0 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 ment is the.** s
159d0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b ize of each look
159e0 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f aside buffer slo
159f0 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 t and the second
15a00 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
15a10 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 f.** slots alloc
15a20 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 ated to each dat
15a30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
15a40 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f .)^ ^(SQLITE_CO
15a50 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a NFIG_LOOKASIDE.*
15a60 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 * sets the <i>de
15a70 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 fault</i> lookas
15a80 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 ide size. The [S
15a90 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
15aa0 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 OOKASIDE].** opt
15ab0 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ion to [sqlite3_
15ac0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e db_config()] can
15ad0 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e be used to chan
15ae0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 ge the lookaside
15af0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f .** configuratio
15b00 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 n on individual
15b10 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c connections.)^ <
15b20 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
15b30 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
15b40 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f E2]] <dt>SQLITE_
15b50 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f CONFIG_PCACHE2</
15b60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
15b70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
15b80 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 PCACHE2 option t
15b90 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
15ba0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
15bb0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f .** a pointer to
15bc0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 an [sqlite3_pca
15bd0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 che_methods2] ob
15be0 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 ject. This obje
15bf0 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 ct specifies.**
15c00 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f the interface to
15c10 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 a custom page c
15c20 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
15c30 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 ion.)^.** ^SQLit
15c40 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
15c50 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 f the [sqlite3_p
15c60 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 cache_methods2]
15c70 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a object.</dd>.**.
15c80 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
15c90 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 IG_GETPCACHE2]]
15ca0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
15cb0 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 G_GETPCACHE2</dt
15cc0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 >.** <dd> ^(The
15cd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
15ce0 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 TPCACHE2 option
15cf0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
15d00 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a rgument which.**
15d10 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
15d20 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 an [sqlite3_pca
15d30 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 che_methods2] ob
15d40 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f ject. SQLite co
15d50 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 pies of.** the c
15d60 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 urrent page cach
15d70 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
15d80 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 into that objec
15d90 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a t.)^ </dd>.**.**
15da0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
15db0 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 _LOG]] <dt>SQLIT
15dc0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 E_CONFIG_LOG</dt
15dd0 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 >.** <dd> The SQ
15de0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 LITE_CONFIG_LOG
15df0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 option is used t
15e00 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 o configure the
15e10 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c SQLite.** global
15e20 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a [error log]..**
15e30 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f (^The SQLITE_CO
15e40 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 NFIG_LOG option
15e50 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 takes two argume
15e60 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 nts: a pointer t
15e70 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 o a.** function
15e80 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e with a call sign
15e90 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 ature of void(*)
15ea0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
15eb0 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 char*), .** and
15ec0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f a pointer to vo
15ed0 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 id. ^If the func
15ee0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 tion pointer is
15ef0 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a not NULL, it is.
15f00 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 ** invoked by [s
15f10 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f qlite3_log()] to
15f20 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f process each lo
15f30 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 gging event. ^I
15f40 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f f the.** functio
15f50 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c n pointer is NUL
15f60 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f L, the [sqlite3_
15f70 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 log()] interface
15f80 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 becomes a no-op
15f90 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 ..** ^The void p
15fa0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 ointer that is t
15fb0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
15fc0 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e nt to SQLITE_CON
15fd0 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 FIG_LOG is.** pa
15fe0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 ssed through as
15ff0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
16000 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 ter to the appli
16010 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c cation-defined l
16020 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f ogger.** functio
16030 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 n whenever that
16040 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f function is invo
16050 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e ked. ^The secon
16060 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a d parameter to.*
16070 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e * the logger fun
16080 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 ction is a copy
16090 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 of the first par
160a0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f ameter to the co
160b0 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b rresponding.** [
160c0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 sqlite3_log()] c
160d0 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e all and is inten
160e0 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 ded to be a [res
160f0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a ult code] or an.
16100 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
16110 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 ult code]. ^The
16120 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
16130 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c passed to the l
16140 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 ogger is.** log
16150 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f message after fo
16160 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 rmatting via [sq
16170 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
16180 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 ]..** The SQLite
16190 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 logging interfa
161a0 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 ce is not reentr
161b0 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 ant; the logger
161c0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 function.** supp
161d0 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c lied by the appl
161e0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ication must not
161f0 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 invoke any SQLi
16200 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a te interface..**
16210 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 In a multi-thre
16220 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e aded application
16230 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f , the applicatio
16240 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 n-defined logger
16250 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 .** function mus
16260 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e t be threadsafe.
16270 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
16280 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 QLITE_CONFIG_URI
16290 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
162a0 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e NFIG_URI.** <dd>
162b0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^(The SQLITE_CON
162c0 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 FIG_URI option t
162d0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
162e0 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 gument of type i
162f0 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 nt..** If non-ze
16300 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e ro, then URI han
16310 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c dling is globall
16320 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 y enabled. If th
16330 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a e parameter is z
16340 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 ero,.** then URI
16350 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f handling is glo
16360 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 bally disabled.)
16370 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 ^ ^If URI handli
16380 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a ng is globally.*
16390 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 * enabled, all f
163a0 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 ilenames passed
163b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
163c0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
163d0 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 en_v2()],.** [sq
163e0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 lite3_open16()]
163f0 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 or.** specified
16400 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 as part of [ATTA
16410 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 CH] commands are
16420 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
16430 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 URIs, regardless
16440 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f .** of whether o
16450 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 r not the [SQLIT
16460 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 E_OPEN_URI] flag
16470 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 is set when the
16480 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e database.** con
16490 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 nection is opene
164a0 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f d. ^If it is glo
164b0 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 bally disabled,
164c0 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a filenames are.**
164d0 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 only interprete
164e0 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 d as URIs if the
164f0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 SQLITE_OPEN_URI
16500 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 flag is set whe
16510 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 n the.** databas
16520 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
16530 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 opened. ^(By def
16540 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 ault, URI handli
16550 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a ng is globally.*
16560 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 * disabled. The
16570 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 default value ma
16580 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 y be changed by
16590 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 compiling with t
165a0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 he.** [SQLITE_US
165b0 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 E_URI] symbol de
165c0 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b fined.)^.**.** [
165d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 [SQLITE_CONFIG_C
165e0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 OVERING_INDEX_SC
165f0 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f AN]] <dt>SQLITE_
16600 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f CONFIG_COVERING_
16610 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 INDEX_SCAN.** <d
16620 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f d>^The SQLITE_CO
16630 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e NFIG_COVERING_IN
16640 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 DEX_SCAN option
16650 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 takes a single i
16660 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 nteger.** argume
16670 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 nt which is inte
16680 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f rpreted as a boo
16690 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f lean in order to
166a0 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 enable or disab
166b0 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 le.** the use of
166c0 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 covering indice
166d0 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 s for full table
166e0 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 scans in the qu
166f0 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a ery optimizer..*
16700 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 * ^The default s
16710 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d etting is determ
16720 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b ined.** by the [
16730 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 SQLITE_ALLOW_COV
16740 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e ERING_INDEX_SCAN
16750 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
16760 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e ption, or is "on
16770 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d ".** if that com
16780 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
16790 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 is omitted..**
167a0 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 The ability to d
167b0 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f isable the use o
167c0 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 f covering indic
167d0 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c es for full tabl
167e0 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 e scans.** is be
167f0 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 cause some incor
16800 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 rectly coded leg
16810 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 acy applications
16820 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 might malfuncti
16830 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f on.** when the o
16840 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 ptimization is e
16850 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 nabled. Providi
16860 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 ng the ability t
16870 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 o.** disable the
16880 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c optimization al
16890 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 lows the older,
168a0 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f buggy applicatio
168b0 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a n code to work.*
168c0 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 * without change
168d0 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 even with newer
168e0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
168f0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c ite..**.** [[SQL
16900 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
16910 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e E]] [[SQLITE_CON
16920 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a FIG_GETPCACHE]].
16930 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
16940 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 NFIG_PCACHE and
16950 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
16960 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 TPCACHE.** <dd>
16970 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 These options ar
16980 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 e obsolete and s
16990 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 hould not be use
169a0 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a d by new code..*
169b0 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 * They are retai
169c0 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 ned for backward
169d0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 s compatibility
169e0 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f but are now no-o
169f0 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a ps..** </dd>.**.
16a00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
16a10 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c IG_SQLLOG]].** <
16a20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
16a30 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 _SQLLOG.** <dd>T
16a40 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e his option is on
16a50 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 ly available if
16a60 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c sqlite is compil
16a70 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ed with the.** [
16a80 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 SQLITE_ENABLE_SQ
16a90 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 LLOG] pre-proces
16aa0 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 sor macro define
16ab0 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 d. The first arg
16ac0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 ument should.**
16ad0 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 be a pointer to
16ae0 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 a function of ty
16af0 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a pe void(*)(void*
16b00 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 ,sqlite3*,const
16b10 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 char*, int)..**
16b20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c The second shoul
16b30 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f d be of type (vo
16b40 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 id*). The callba
16b50 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 ck is invoked by
16b60 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 the library.**
16b70 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 in three separat
16b80 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c e circumstances,
16b90 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 identified by t
16ba0 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 he value passed
16bb0 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 as the.** fourth
16bc0 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 parameter. If t
16bd0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
16be0 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 ter is 0, then t
16bf0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
16c00 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 ection.** passed
16c10 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 as the second a
16c20 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 rgument has just
16c30 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 been opened. Th
16c40 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
16c50 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 .** points to a
16c60 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e buffer containin
16c70 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 g the name of th
16c80 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 e main database
16c90 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 file. If the.**
16ca0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
16cb0 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 is 1, then the
16cc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 SQL statement th
16cd0 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 at the third par
16ce0 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 ameter.** points
16cf0 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 to has just bee
16d00 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 n executed. Or,
16d10 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 if the fourth pa
16d20 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 rameter is 2, th
16d30 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 en.** the connec
16d40 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 tion being passe
16d50 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
16d60 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 parameter is bei
16d70 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a ng closed. The.*
16d80 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 * third paramete
16d90 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c r is passed NULL
16da0 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 In this case.
16db0 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 An example of us
16dc0 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 ing this.** conf
16dd0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
16de0 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 can be seen in
16df0 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 the "test_sqllog
16e00 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 .c" source file
16e10 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 in.** the canoni
16e20 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 cal SQLite sourc
16e30 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a e tree.</dd>.**.
16e40 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
16e50 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a IG_MMAP_SIZE]].*
16e60 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
16e70 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a FIG_MMAP_SIZE.**
16e80 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e <dd>^SQLITE_CON
16e90 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 FIG_MMAP_SIZE ta
16ea0 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 kes two 64-bit i
16eb0 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f nteger (sqlite3_
16ec0 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a int64) values.**
16ed0 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 that are the de
16ee0 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 fault mmap size
16ef0 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 limit (the defau
16f00 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a lt setting for.*
16f10 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 * [PRAGMA mmap_s
16f20 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 ize]) and the ma
16f30 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d ximum allowed mm
16f40 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a ap size limit..*
16f50 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 * ^The default s
16f60 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 etting can be ov
16f70 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 erridden by each
16f80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
16f90 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 tion using.** ei
16fa0 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 ther the [PRAGMA
16fb0 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d mmap_size] comm
16fc0 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 and, or by using
16fd0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
16fe0 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d FCNTL_MMAP_SIZE]
16ff0 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 file control.
17000 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c ^(The maximum al
17010 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a lowed mmap size.
17020 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e ** will be silen
17030 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 tly truncated if
17040 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 necessary so th
17050 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 at it does not e
17060 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d xceed the.** com
17070 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 pile-time maximu
17080 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 m mmap size set
17090 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 by the.** [SQLIT
170a0 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d E_MAX_MMAP_SIZE]
170b0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
170c0 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 tion.)^.** ^If e
170d0 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 ither argument t
170e0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 o this option is
170f0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
17100 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 that argument is
17110 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 .** changed to i
17120 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 ts compile-time
17130 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b default..**.** [
17140 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 [SQLITE_CONFIG_W
17150 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a IN32_HEAPSIZE]].
17160 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
17170 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 NFIG_WIN32_HEAPS
17180 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 IZE.** <dd>^The
17190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 SQLITE_CONFIG_WI
171a0 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 N32_HEAPSIZE opt
171b0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 ion is only avai
171c0 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 lable if SQLite
171d0 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 is.** compiled f
171e0 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 or Windows with
171f0 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 the [SQLITE_WIN3
17200 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 2_MALLOC] pre-pr
17210 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a ocessor macro.**
17220 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 defined. ^SQLIT
17230 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 E_CONFIG_WIN32_H
17240 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 EAPSIZE takes a
17250 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 32-bit unsigned
17260 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a integer value.**
17270 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 that specifies
17280 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 the maximum size
17290 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 of the created
172a0 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 heap..**.** [[SQ
172b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
172c0 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 HE_HDRSZ]].** <d
172d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
172e0 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 PCACHE_HDRSZ.**
172f0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f <dd>^The SQLITE_
17300 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 CONFIG_PCACHE_HD
17310 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 RSZ option takes
17320 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 a single parame
17330 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ter which.** is
17340 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
17350 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 integer and writ
17360 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 es into that int
17370 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 eger the number
17380 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 of extra.** byte
17390 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 s per page requi
173a0 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 red for each pag
173b0 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e e in [SQLITE_CON
173c0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a FIG_PAGECACHE]..
173d0 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 ** The amount of
173e0 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 extra space req
173f0 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 uired can change
17400 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
17410 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 e compiler,.** t
17420 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 arget platform,
17430 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 and SQLite versi
17440 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 on..**.** [[SQLI
17450 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d TE_CONFIG_PMASZ]
17460 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f ].** <dt>SQLITE_
17470 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 CONFIG_PMASZ.**
17480 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f <dd>^The SQLITE_
17490 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 CONFIG_PMASZ opt
174a0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
174b0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 le parameter whi
174c0 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 ch.** is an unsi
174d0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 gned integer and
174e0 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d sets the "Minim
174f0 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 um PMA Size" for
17500 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 the multithread
17510 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 ed.** sorter to
17520 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 that integer. T
17530 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d he default minim
17540 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 um PMA Size is s
17550 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 et by the.** [SQ
17560 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 LITE_SORTER_PMAS
17570 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 Z] compile-time
17580 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 option. New thr
17590 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 eads are launche
175a0 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 d.** to help wit
175b0 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e h sort operation
175c0 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 s when multithre
175d0 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 aded sorting.**
175e0 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e is enabled (usin
175f0 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 g the [PRAGMA th
17600 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 reads] command)
17610 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f and the amount o
17620 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 f content.** to
17630 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 be sorted exceed
17640 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 s the page size
17650 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 times the minimu
17660 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 m of the.** [PRA
17670 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 GMA cache_size]
17680 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 setting and this
17690 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b value..**.** [[
176a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 SQLITE_CONFIG_ST
176b0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a MTJRNL_SPILL]].*
176c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
176d0 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 FIG_STMTJRNL_SPI
176e0 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 LL.** <dd>^The S
176f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d QLITE_CONFIG_STM
17700 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 TJRNL_SPILL opti
17710 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
17720 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 e parameter whic
17730 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 h.** becomes the
17740 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 [statement jour
17750 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 nal] spill-to-di
17760 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a sk threshold. .
17770 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f ** [Statement jo
17780 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 urnals] are held
17790 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c in memory until
177a0 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 their size (in
177b0 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 bytes).** exceed
177c0 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 s this threshold
177d0 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 , at which point
177e0 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65 they are writte
177f0 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 n to disk..** Or
17800 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c if the threshol
17810 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 d is -1, stateme
17820 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 nt journals are
17830 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 always held.** e
17840 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 xclusively in me
17850 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d mory..** Since m
17860 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f any statement jo
17870 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 urnals never bec
17880 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 ome large, setti
17890 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 ng the spill.**
178a0 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 threshold to a v
178b0 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b alue such as 64K
178c0 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 iB can greatly r
178d0 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 educe the amount
178e0 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 of.** I/O requi
178f0 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 red to support s
17900 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 tatement rollbac
17910 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c k..** The defaul
17920 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 t value for this
17930 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 setting is cont
17940 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a rolled by the.**
17950 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e [SQLITE_STMTJRN
17960 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 L_SPILL] compile
17970 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a -time option..**
17980 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
17990 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 FIG_SORTERREF_SI
179a0 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 ZE]].** <dt>SQLI
179b0 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 TE_CONFIG_SORTER
179c0 52 45 46 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e REF_SIZE.** <dd>
179d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
179e0 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 G_SORTERREF_SIZE
179f0 20 6f 70 74 69 6f 6e 20 61 63 63 65 70 74 73 20 option accepts
17a00 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 a single paramet
17a10 65 72 0a 2a 2a 20 6f 66 20 74 79 70 65 20 28 69 er.** of type (i
17a20 6e 74 29 20 2d 20 74 68 65 20 6e 65 77 20 76 61 nt) - the new va
17a30 6c 75 65 20 6f 66 20 74 68 65 20 73 6f 72 74 65 lue of the sorte
17a40 72 2d 72 65 66 65 72 65 6e 63 65 20 73 69 7a 65 r-reference size
17a50 20 74 68 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55 threshold..** U
17a60 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 53 51 4c sually, when SQL
17a70 69 74 65 20 75 73 65 73 20 61 6e 20 65 78 74 65 ite uses an exte
17a80 72 6e 61 6c 20 73 6f 72 74 20 74 6f 20 6f 72 64 rnal sort to ord
17a90 65 72 20 72 65 63 6f 72 64 73 20 61 63 63 6f 72 er records accor
17aa0 64 69 6e 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52 ding.** to an OR
17ab0 44 45 52 20 42 59 20 63 6c 61 75 73 65 2c 20 61 DER BY clause, a
17ac0 6c 6c 20 66 69 65 6c 64 73 20 72 65 71 75 69 72 ll fields requir
17ad0 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 ed by the caller
17ae0 20 61 72 65 20 70 72 65 73 65 6e 74 20 69 6e 20 are present in
17af0 74 68 65 0a 2a 2a 20 73 6f 72 74 65 64 20 72 65 the.** sorted re
17b00 63 6f 72 64 73 2e 20 48 6f 77 65 76 65 72 2c 20 cords. However,
17b10 69 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d if SQLite determ
17b20 69 6e 65 73 20 62 61 73 65 64 20 6f 6e 20 74 68 ines based on th
17b30 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 0a e declared type.
17b40 2a 2a 20 6f 66 20 61 20 74 61 62 6c 65 20 63 6f ** of a table co
17b50 6c 75 6d 6e 20 74 68 61 74 20 69 74 73 20 76 61 lumn that its va
17b60 6c 75 65 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 lues are likely
17b70 74 6f 20 62 65 20 76 65 72 79 20 6c 61 72 67 65 to be very large
17b80 20 2d 20 6c 61 72 67 65 72 0a 2a 2a 20 74 68 61 - larger.** tha
17b90 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 65 64 n the configured
17ba0 20 73 6f 72 74 65 72 2d 72 65 66 65 72 65 6e 63 sorter-referenc
17bb0 65 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c 64 e size threshold
17bc0 20 2d 20 74 68 65 6e 20 61 20 72 65 66 65 72 65 - then a refere
17bd0 6e 63 65 0a 2a 2a 20 69 73 20 73 74 6f 72 65 64 nce.** is stored
17be0 20 69 6e 20 65 61 63 68 20 73 6f 72 74 65 64 20 in each sorted
17bf0 72 65 63 6f 72 64 20 61 6e 64 20 74 68 65 20 72 record and the r
17c00 65 71 75 69 72 65 64 20 63 6f 6c 75 6d 6e 20 76 equired column v
17c10 61 6c 75 65 73 20 6c 6f 61 64 65 64 0a 2a 2a 20 alues loaded.**
17c20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 from the databas
17c30 65 20 61 73 20 72 65 63 6f 72 64 73 20 61 72 65 e as records are
17c40 20 72 65 74 75 72 6e 65 64 20 69 6e 20 73 6f 72 returned in sor
17c50 74 65 64 20 6f 72 64 65 72 2e 20 54 68 65 20 64 ted order. The d
17c60 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 efault.** value
17c70 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 for this option
17c80 69 73 20 74 6f 20 6e 65 76 65 72 20 75 73 65 20 is to never use
17c90 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f this optimizatio
17ca0 6e 2e 20 53 70 65 63 69 66 79 69 6e 67 20 61 20 n. Specifying a
17cb0 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 76 61 6c .** negative val
17cc0 75 65 20 66 6f 72 20 74 68 69 73 20 6f 70 74 69 ue for this opti
17cd0 6f 6e 20 72 65 73 74 6f 72 65 73 20 74 68 65 20 on restores the
17ce0 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 75 default behaviou
17cf0 72 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f r..** This optio
17d00 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 n is only availa
17d10 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 ble if SQLite is
17d20 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
17d30 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e he.** [SQLITE_EN
17d40 41 42 4c 45 5f 53 4f 52 54 45 52 5f 52 45 46 45 ABLE_SORTER_REFE
17d50 52 45 4e 43 45 53 5d 20 63 6f 6d 70 69 6c 65 2d RENCES] compile-
17d60 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 time option..**
17d70 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </dl>.*/.#define
17d80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
17d90 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 INGLETHREAD 1
17da0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
17db0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
17dc0 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 MULTITHREAD 2
17dd0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
17de0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
17df0 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 _SERIALIZED 3
17e00 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
17e10 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
17e20 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 G_MALLOC
17e30 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 4 /* sqlite3_me
17e40 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 m_methods* */.#d
17e50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
17e60 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 FIG_GETMALLOC
17e70 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 5 /* sqlite3_
17e80 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a mem_methods* */.
17e90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
17ea0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 ONFIG_SCRATCH
17eb0 20 20 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 6 /* No lon
17ec0 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 ger used */.#def
17ed0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
17ee0 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 G_PAGECACHE
17ef0 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 7 /* void*, int
17f00 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 sz, int N */.#d
17f10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
17f20 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 FIG_HEAP
17f30 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 8 /* void*, i
17f40 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 nt nByte, int mi
17f50 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c n */.#define SQL
17f60 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
17f70 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 ATUS 9 /* b
17f80 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e oolean */.#defin
17f90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
17fa0 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 MUTEX 10
17fb0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 /* sqlite3_mute
17fc0 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 x_methods* */.#d
17fd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
17fe0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 FIG_GETMUTEX
17ff0 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 11 /* sqlite3_
18000 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a mutex_methods* *
18010 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 /./* previously
18020 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 SQLITE_CONFIG_CH
18030 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 UNKALLOC 12 whic
18040 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e h is now unused.
18050 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c */ .#define SQL
18060 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
18070 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 SIDE 13 /* i
18080 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e nt int */.#defin
18090 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
180a0 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 PCACHE 14
180b0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 /* no-op */.#de
180c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
180d0 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 IG_GETPCACHE
180e0 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 15 /* no-op */.
180f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
18100 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 ONFIG_LOG
18110 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 16 /* xFunc,
18120 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e void* */.#defin
18130 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
18140 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 URI 17
18150 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 /* int */.#defi
18160 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18170 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 _PCACHE2 18
18180 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 /* sqlite3_pca
18190 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f che_methods2* */
181a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
181b0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
181c0 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 2 19 /* sqlit
181d0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
181e0 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 s2* */.#define S
181f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 QLITE_CONFIG_COV
18200 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e ERING_INDEX_SCAN
18210 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 20 /* int */.#
18220 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
18230 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 NFIG_SQLLOG
18240 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 21 /* xSqllog
18250 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 , void* */.#defi
18260 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18270 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 _MMAP_SIZE 22
18280 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 /* sqlite3_int
18290 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 64, sqlite3_int6
182a0 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 4 */.#define SQL
182b0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 ITE_CONFIG_WIN32
182c0 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 _HEAPSIZE 2
182d0 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 3 /* int nByte
182e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
182f0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f E_CONFIG_PCACHE_
18300 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 HDRSZ 24
18310 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a /* int *psz */.
18320 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
18330 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 ONFIG_PMASZ
18340 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 25 /*
18350 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a unsigned int sz
18360 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 Pma */.#define S
18370 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d QLITE_CONFIG_STM
18380 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 TJRNL_SPILL
18390 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 26 /* int nByt
183a0 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
183b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c ITE_CONFIG_SMALL
183c0 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 _MALLOC 2
183d0 37 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 7 /* boolean */
183e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
183f0 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 CONFIG_SORTERREF
18400 5f 53 49 5a 45 20 20 20 20 20 20 32 38 20 20 2f _SIZE 28 /
18410 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a * int nByte */..
18420 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
18430 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
18440 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f ion Configuratio
18450 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 n Options.**.**
18460 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
18470 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c are the availabl
18480 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 e integer config
18490 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
184a0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 that.** can be p
184b0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 assed as the sec
184c0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
184d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f the [sqlite3_db_
184e0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
184f0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 ace..**.** New c
18500 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
18510 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 ions may be adde
18520 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
18530 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
18540 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 ** Existing conf
18550 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
18560 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f s might be disco
18570 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 ntinued. Applic
18580 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
18590 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 check the retur
185a0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c n code from [sql
185b0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
185c0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 ] to make sure t
185d0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 hat.** the call
185e0 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 worked. ^The [s
185f0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
18600 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 ()] interface wi
18610 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e ll return a.** n
18620 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 on-zero [error c
18630 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e ode] if a discon
18640 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 tinued or unsupp
18650 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 orted configurat
18660 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 ion option.** is
18670 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
18680 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 <dl>.** <dt>SQLI
18690 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
186a0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ASIDE</dt>.** <d
186b0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
186c0 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 takes three addi
186d0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 tional arguments
186e0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 that determine
186f0 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 the .** [lookasi
18700 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 de memory alloca
18710 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 tor] configurati
18720 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 on for the [data
18730 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
18740 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 ..** ^The first
18750 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 argument (the th
18760 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
18770 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
18780 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 fig()] is a.** p
18790 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f ointer to a memo
187a0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 ry buffer to use
187b0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d for lookaside m
187c0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 emory..** ^The f
187d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 irst argument af
187e0 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 ter the SQLITE_D
187f0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
18800 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 E verb.** may be
18810 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 NULL in which c
18820 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 ase SQLite will
18830 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 allocate the.**
18840 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 lookaside buffer
18850 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 itself using [s
18860 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
18870 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 . ^The second ar
18880 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a gument is the.**
18890 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f size of each lo
188a0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 okaside buffer s
188b0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 lot. ^The third
188c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
188d0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c number of.** sl
188e0 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f ots. The size o
188f0 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 f the buffer in
18900 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
18910 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 nt must be great
18920 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 er than.** or eq
18930 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 ual to the produ
18940 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 ct of the second
18950 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d and third argum
18960 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 ents. The buffe
18970 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 r.** must be ali
18980 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 gned to an 8-byt
18990 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 e boundary. ^If
189a0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
189b0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 ment to.** SQLIT
189c0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
189d0 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 SIDE is not a mu
189e0 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 ltiple of 8, it
189f0 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a is internally.**
18a00 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f rounded down to
18a10 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 the next smalle
18a20 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e r multiple of 8.
18a30 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 ^(The lookasid
18a40 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 e memory.** conf
18a50 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 iguration for a
18a60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18a70 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ion can only be
18a80 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 changed when tha
18a90 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 t.** connection
18aa0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 is not currently
18ab0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 using lookaside
18ac0 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f memory, or in o
18ad0 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 ther words.** wh
18ae0 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 en the "current
18af0 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 value" returned
18b00 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 by.** [sqlite3_d
18b10 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c b_status](D,[SQL
18b20 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
18b30 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 SIDE],...) is ze
18b40 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d ro..** Any attem
18b50 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 pt to change the
18b60 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
18b70 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 y configuration
18b80 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a when lookaside.*
18b90 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 * memory is in u
18ba0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f se leaves the co
18bb0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 nfiguration unch
18bc0 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e anged and return
18bd0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 s .** [SQLITE_BU
18be0 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a SY].)^</dd>.**.*
18bf0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 * <dt>SQLITE_DBC
18c00 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 ONFIG_ENABLE_FKE
18c10 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e Y</dt>.** <dd> ^
18c20 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 This option is u
18c30 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 sed to enable or
18c40 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 disable the enf
18c50 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b orcement of.** [
18c60 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 foreign key cons
18c70 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 traints]. There
18c80 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 should be two a
18c90 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 dditional argume
18ca0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 nts..** The firs
18cb0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e t argument is an
18cc0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 integer which i
18cd0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 s 0 to disable F
18ce0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a K enforcement,.*
18cf0 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e * positive to en
18d00 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d able FK enforcem
18d10 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 ent or negative
18d20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f to leave FK enfo
18d30 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 rcement.** uncha
18d40 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e nged. The secon
18d50 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 d parameter is a
18d60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
18d70 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 nteger into whic
18d80 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 h.** is written
18d90 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 0 or 1 to indica
18da0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e te whether FK en
18db0 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 forcement is off
18dc0 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 or on.** follow
18dd0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 ing this call.
18de0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
18df0 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 eter may be a NU
18e00 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a LL pointer, in.*
18e10 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 * which case the
18e20 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 FK enforcement
18e30 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 setting is not r
18e40 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f eported back. </
18e50 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
18e60 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e LITE_DBCONFIG_EN
18e70 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 ABLE_TRIGGER</dt
18e80 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 >.** <dd> ^This
18e90 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 option is used t
18ea0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 o enable or disa
18eb0 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 ble [CREATE TRIG
18ec0 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e GER | triggers].
18ed0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 .** There should
18ee0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e be two addition
18ef0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a al arguments..**
18f00 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
18f10 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ent is an intege
18f20 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 r which is 0 to
18f30 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 disable triggers
18f40 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f ,.** positive to
18f50 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 enable triggers
18f60 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 or negative to
18f70 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e leave the settin
18f80 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 g unchanged..**
18f90 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
18fa0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 eter is a pointe
18fb0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 r to an integer
18fc0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 into which.** is
18fd0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 written 0 or 1
18fe0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 to indicate whet
18ff0 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 her triggers are
19000 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 disabled or ena
19010 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e bled.** followin
19020 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 g this call. Th
19030 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
19040 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c er may be a NULL
19050 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 pointer, in.**
19060 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 which case the t
19070 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 rigger setting i
19080 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 s not reported b
19090 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ack. </dd>.**.**
190a0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
190b0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 NFIG_ENABLE_FTS3
190c0 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a _TOKENIZER</dt>.
190d0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
190e0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
190f0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
19100 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 e the two-argume
19110 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 nt.** version of
19120 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e the [fts3_token
19130 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e izer()] function
19140 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f which is part o
19150 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 f the.** [FTS3]
19160 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 full-text search
19170 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f engine extensio
19180 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 n..** There shou
19190 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 ld be two additi
191a0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a onal arguments..
191b0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
191c0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 ument is an inte
191d0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 ger which is 0 t
191e0 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 o disable fts3_t
191f0 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a okenizer() or.**
19200 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 positive to ena
19210 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a ble fts3_tokeniz
19220 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 er() or negative
19230 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 to leave the se
19240 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 tting.** unchang
19250 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e ed..** The secon
19260 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 d parameter is a
19270 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
19280 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 nteger into whic
19290 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 h.** is written
192a0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 0 or 1 to indica
192b0 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f te whether fts3_
192c0 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 tokenizer is dis
192d0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 abled or enabled
192e0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 .** following th
192f0 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 is call. The se
19300 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d cond parameter m
19310 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 ay be a NULL poi
19320 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 nter, in.** whic
19330 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 h case the new s
19340 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 etting is not re
19350 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 ported back. </d
19360 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
19370 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
19380 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 BLE_LOAD_EXTENSI
19390 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 ON</dt>.** <dd>
193a0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 ^This option is
193b0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f used to enable o
193c0 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73 r disable the [s
193d0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 qlite3_load_exte
193e0 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 nsion()].** inte
193f0 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e rface independen
19400 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 tly of the [load
19410 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 _extension()] SQ
19420 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 L function..** T
19430 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 he [sqlite3_enab
19440 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f le_load_extensio
19450 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 n()] API enables
19460 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74 or disables bot
19470 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b h the.** C-API [
19480 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 sqlite3_load_ext
19490 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 ension()] and th
194a0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b e SQL function [
194b0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
194c0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 ]..** There shou
194d0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 ld be two additi
194e0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a onal arguments..
194f0 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72 73 ** When the firs
19500 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
19510 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 is interface is
19520 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 1, then only the
19530 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 C-API is.** ena
19540 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c bled and the SQL
19550 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e function remain
19560 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 s disabled. If
19570 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
19580 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e nt to.** this in
19590 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74 68 terface is 0, th
195a0 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50 en both the C-AP
195b0 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 I and the SQL fu
195c0 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62 nction are disab
195d0 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 led..** If the f
195e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
195f0 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 -1, then no cha
19600 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f nges are made to
19610 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65 72 state of either
19620 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 the.** C-API or
19630 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
19640 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 n..** The second
19650 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
19660 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
19670 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 teger into which
19680 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 .** is written 0
19690 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 or 1 to indicat
196a0 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74 e whether [sqlit
196b0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f e3_load_extensio
196c0 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a n()] interface.*
196d0 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 * is disabled or
196e0 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 enabled followi
196f0 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 ng this call. T
19700 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
19710 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 ter may.** be a
19720 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e NULL pointer, in
19730 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 which case the
19740 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e new setting is n
19750 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b ot reported back
19760 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ..** </dd>.**.**
19770 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
19780 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c NFIG_MAINDBNAME<
19790 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
197a0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 is option is use
197b0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 d to change the
197c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69 name of the "mai
197d0 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 n" database.** s
197e0 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c chema. ^The sol
197f0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 e argument is a
19800 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e pointer to a con
19810 73 74 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e stant UTF8 strin
19820 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 g.** which will
19830 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 become the new s
19840 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c chema name in pl
19850 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 ace of "main".
19860 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 ^SQLite.** does
19870 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 not make a copy
19880 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 of the new main
19890 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 schema name stri
198a0 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69 ng, so the appli
198b0 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 cation.** must e
198c0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61 nsure that the a
198d0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 rgument passed i
198e0 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49 nto this DBCONFI
198f0 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 G option is unch
19900 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 anged.** until a
19910 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61 73 fter the databas
19920 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f e connection clo
19930 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a ses..** </dd>.**
19940 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
19950 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f BCONFIG_NO_CKPT_
19960 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a ON_CLOSE</dt>.**
19970 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 <dd> Usually, w
19980 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 hen a database i
19990 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c n wal mode is cl
199a0 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 osed or detached
199b0 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 from a .** data
199c0 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c base handle, SQL
199d0 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 ite checks if th
199e0 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 is will mean tha
199f0 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 t there are now
19a00 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f no .** connectio
19a10 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 ns at all to the
19a20 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f database. If so
19a30 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 , it performs a
19a40 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f checkpoint .** o
19a50 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 peration before
19a60 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e closing the conn
19a70 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 ection. This opt
19a80 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 ion may be used
19a90 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 to.** override t
19aa0 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 his behaviour. T
19ab0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
19ac0 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 er passed to thi
19ad0 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 s operation.** i
19ae0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 70 s an integer - p
19af0 6f 73 69 74 69 76 65 20 74 6f 20 64 69 73 61 62 ositive to disab
19b00 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f le checkpoints-o
19b10 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f n-close, or zero
19b20 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 (the.** default
19b30 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d ) to enable them
19b40 2c 20 61 6e 64 20 6e 65 67 61 74 69 76 65 20 74 , and negative t
19b50 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 o leave the sett
19b60 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a ing unchanged..*
19b70 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 * The second par
19b80 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e ameter is a poin
19b90 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
19ba0 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 r.** into which
19bb0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 is written 0 or
19bc0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 1 to indicate wh
19bd0 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 ether checkpoint
19be0 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 s-on-close.** ha
19bf0 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 ve been disabled
19c00 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65 - 0 if they are
19c10 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 not disabled, 1
19c20 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a if they are..**
19c30 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 </dd>.**.** <dt
19c40 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 >SQLITE_DBCONFIG
19c50 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 _ENABLE_QPSG</dt
19c60 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 >.** <dd>^(The S
19c70 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
19c80 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f NABLE_QPSG optio
19c90 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 n activates or d
19ca0 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 eactivates.** th
19cb0 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 e [query planner
19cc0 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72 61 stability guara
19cd0 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57 ntee] (QPSG). W
19ce0 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73 20 hen the QPSG is
19cf0 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e active,.** a sin
19d00 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73 74 gle SQL query st
19d10 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 atement will alw
19d20 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65 ays use the same
19d30 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72 algorithm regar
19d40 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 dless.** of valu
19d50 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 es of [bound par
19d60 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 ameters].)^ The
19d70 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f QPSG disables so
19d80 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a me query optimiz
19d90 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c ations.** that l
19da0 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65 ook at the value
19db0 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d s of bound param
19dc0 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e eters, which can
19dd0 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 make some queri
19de0 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 es.** slower. B
19df0 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73 20 ut the QPSG has
19e00 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66 the advantage of
19e10 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c more predictabl
19e20 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74 e behavior. Wit
19e30 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63 h.** the QPSG ac
19e40 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c tive, SQLite wil
19e50 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 l always use the
19e60 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e same query plan
19e70 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73 in the field as
19e80 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75 72 .** was used dur
19e90 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74 ing testing in t
19ea0 68 65 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66 he lab..** The f
19eb0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
19ec0 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 this setting is
19ed0 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 an integer whic
19ee0 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c h is 0 to disabl
19ef0 65 20 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c 20 e .** the QPSG,
19f00 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 positive to enab
19f10 6c 65 20 51 50 53 47 2c 20 6f 72 20 6e 65 67 61 le QPSG, or nega
19f20 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 tive to leave th
19f30 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 e setting.** unc
19f40 68 61 6e 67 65 64 2e 20 54 68 65 20 73 65 63 6f hanged. The seco
19f50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
19f60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
19f70 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 integer into whi
19f80 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e ch.** is written
19f90 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 0 or 1 to indic
19fa0 61 74 65 20 77 68 65 74 68 65 72 20 74 68 65 20 ate whether the
19fb0 51 50 53 47 20 69 73 20 64 69 73 61 62 6c 65 64 QPSG is disabled
19fc0 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 or enabled.** f
19fd0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 ollowing this ca
19fe0 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a ll..** </dd>.**.
19ff0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 ** <dt>SQLITE_DB
1a000 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 CONFIG_TRIGGER_E
1a010 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 QP</dt>.** <dd>
1a020 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 By default, the
1a030 6f 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49 output of EXPLAI
1a040 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d N QUERY PLAN com
1a050 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a mands does not .
1a060 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75 ** include outpu
1a070 74 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74 t for any operat
1a080 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62 ions performed b
1a090 79 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 y trigger progra
1a0a0 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69 ms. This.** opti
1a0b0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 on is used to se
1a0c0 74 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20 t or clear (the
1a0d0 64 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20 default) a flag
1a0e0 74 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69 that governs thi
1a0f0 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54 s.** behavior. T
1a100 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
1a110 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 er passed to thi
1a120 73 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 s operation is a
1a130 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70 n integer -.** p
1a140 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c ositive to enabl
1a150 65 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69 e output for tri
1a160 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f gger programs, o
1a170 72 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c r zero to disabl
1a180 65 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61 e it,.** or nega
1a190 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 tive to leave th
1a1a0 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e e setting unchan
1a1b0 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f ged..** The seco
1a1c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
1a1d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
1a1e0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 integer into whi
1a1f0 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a ch is written .*
1a200 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 * 0 or 1 to indi
1a210 63 61 74 65 20 77 68 65 74 68 65 72 20 6f 75 74 cate whether out
1a220 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73 put-for-triggers
1a230 20 68 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c has been disabl
1a240 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74 ed - 0 if .** it
1a250 20 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 is not disabled
1a260 2c 20 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a , 1 if it is. .
1a270 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ** </dd>.**.** <
1a280 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
1a290 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 IG_RESET_DATABAS
1a2a0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 53 E</dt>.** <dd> S
1a2b0 65 74 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 et the SQLITE_DB
1a2c0 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 CONFIG_RESET_DAT
1a2d0 41 42 41 53 45 20 66 6c 61 67 20 61 6e 64 20 74 ABASE flag and t
1a2e0 68 65 6e 20 72 75 6e 0a 2a 2a 20 5b 56 41 43 55 hen run.** [VACU
1a2f0 55 4d 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 UM] in order to
1a300 72 65 73 65 74 20 61 20 64 61 74 61 62 61 73 65 reset a database
1a310 20 62 61 63 6b 20 74 6f 20 61 6e 20 65 6d 70 74 back to an empt
1a320 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 77 69 y database.** wi
1a330 74 68 20 6e 6f 20 73 63 68 65 6d 61 20 61 6e 64 th no schema and
1a340 20 6e 6f 20 63 6f 6e 74 65 6e 74 2e 20 54 68 65 no content. The
1a350 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 63 65 following proce
1a360 73 73 20 77 6f 72 6b 73 20 65 76 65 6e 20 66 6f ss works even fo
1a370 72 0a 2a 2a 20 61 20 62 61 64 6c 79 20 63 6f 72 r.** a badly cor
1a380 72 75 70 74 65 64 20 64 61 74 61 62 61 73 65 20 rupted database
1a390 66 69 6c 65 3a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a file:.** <ol>.**
1a3a0 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64 62 <li> sqlite3_db
1a3b0 5f 63 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c 49 _config(db, SQLI
1a3c0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 TE_DBCONFIG_RESE
1a3d0 54 5f 44 41 54 41 42 41 53 45 2c 20 31 2c 20 30 T_DATABASE, 1, 0
1a3e0 29 3b 0a 2a 2a 20 3c 6c 69 3e 20 5b 73 71 6c 69 );.** <li> [sqli
1a3f0 74 65 33 5f 65 78 65 63 5d 28 64 62 2c 20 22 5b te3_exec](db, "[
1a400 56 41 43 55 55 4d 5d 22 2c 20 30 2c 20 30 2c 20 VACUUM]", 0, 0,
1a410 30 29 3b 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 0);.** <li> sqli
1a420 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64 62 te3_db_config(db
1a430 2c 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 , SQLITE_DBCONFI
1a440 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 G_RESET_DATABASE
1a450 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c , 0, 0);.** </ol
1a460 3e 0a 2a 2a 20 42 65 63 61 75 73 65 20 72 65 73 >.** Because res
1a470 65 74 74 69 6e 67 20 61 20 64 61 74 61 62 61 73 etting a databas
1a480 65 20 69 73 20 64 65 73 74 72 75 63 74 69 76 65 e is destructive
1a490 20 61 6e 64 20 69 72 72 65 76 65 72 73 69 62 6c and irreversibl
1a4a0 65 2c 20 74 68 65 0a 2a 2a 20 70 72 6f 63 65 73 e, the.** proces
1a4b0 73 20 72 65 71 75 69 72 65 73 20 74 68 65 20 75 s requires the u
1a4c0 73 65 20 6f 66 20 74 68 69 73 20 6f 62 73 63 75 se of this obscu
1a4d0 72 65 20 41 50 49 20 61 6e 64 20 6d 75 6c 74 69 re API and multi
1a4e0 70 6c 65 20 73 74 65 70 73 20 74 6f 20 68 65 6c ple steps to hel
1a4f0 70 0a 2a 2a 20 65 6e 73 75 72 65 20 74 68 61 74 p.** ensure that
1a500 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 68 61 70 it does not hap
1a510 70 65 6e 20 62 79 20 61 63 63 69 64 65 6e 74 2e pen by accident.
1a520 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 .** </dd>.** </d
1a530 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
1a540 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 LITE_DBCONFIG_MA
1a550 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 INDBNAME
1a560 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 1000 /* cons
1a570 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 t char* */.#defi
1a580 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
1a590 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 IG_LOOKASIDE
1a5a0 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 1001 /*
1a5b0 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a void* int int *
1a5c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1a5d0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
1a5e0 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 _FKEY
1a5f0 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 1002 /* int int*
1a600 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1a610 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
1a620 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 LE_TRIGGER
1a630 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 1003 /* int in
1a640 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t* */.#define SQ
1a650 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e LITE_DBCONFIG_EN
1a660 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 ABLE_FTS3_TOKENI
1a670 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 ZER 1004 /* int
1a680 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int* */.#define
1a690 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
1a6a0 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 ENABLE_LOAD_EXTE
1a6b0 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e NSION 1005 /* in
1a6c0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e t int* */.#defin
1a6d0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
1a6e0 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f G_NO_CKPT_ON_CLO
1a6f0 53 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 SE 1006 /*
1a700 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 int int* */.#def
1a710 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e ine SQLITE_DBCON
1a720 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 FIG_ENABLE_QPSG
1a730 20 20 20 20 20 20 20 20 20 20 31 30 30 37 20 2f 1007 /
1a740 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 * int int* */.#d
1a750 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 efine SQLITE_DBC
1a760 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 ONFIG_TRIGGER_EQ
1a770 50 20 20 20 20 20 20 20 20 20 20 20 31 30 30 38 P 1008
1a780 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a /* int int* */.
1a790 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1a7a0 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 BCONFIG_RESET_DA
1a7b0 54 41 42 41 53 45 20 20 20 20 20 20 20 20 31 30 TABASE 10
1a7c0 30 39 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 09 /* int int* *
1a7d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1a7e0 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 58 20 20 20 _DBCONFIG_MAX
1a7f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1a800 31 30 30 39 20 2f 2a 20 4c 61 72 67 65 73 74 20 1009 /* Largest
1a810 44 42 43 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a 0a DBCONFIG */../*.
1a820 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 ** CAPI3REF: Ena
1a830 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 ble Or Disable E
1a840 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 xtended Result C
1a850 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 odes.** METHOD:
1a860 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
1a870 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e he sqlite3_exten
1a880 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 ded_result_codes
1a890 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c () routine enabl
1a8a0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 es or disables t
1a8b0 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 he.** [extended
1a8c0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 result codes] fe
1a8d0 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e ature of SQLite.
1a8e0 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 ^The extended r
1a8f0 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 esult.** codes a
1a900 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 re disabled by d
1a910 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f efault for histo
1a920 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c rical compatibil
1a930 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ity..*/.int sqli
1a940 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 te3_extended_res
1a950 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 ult_codes(sqlite
1a960 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 3*, int onoff);.
1a970 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1a980 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 Last Insert Row
1a990 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 id.** METHOD: sq
1a9a0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 lite3.**.** ^Eac
1a9b0 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 h entry in most
1a9c0 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 SQLite tables (e
1a9d0 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f xcept for [WITHO
1a9e0 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 UT ROWID] tables
1a9f0 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 ).** has a uniqu
1aa00 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a e 64-bit signed.
1aa10 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 ** integer key c
1aa20 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 alled the [ROWID
1aa30 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 | "rowid"]. ^Th
1aa40 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 e rowid is alway
1aa50 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 s available.** a
1aa60 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 s an undeclared
1aa70 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 column named ROW
1aa80 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 ID, OID, or _ROW
1aa90 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 ID_ as long as t
1aaa0 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 hose.** names ar
1aab0 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 e not also used
1aac0 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 by explicitly de
1aad0 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 clared columns.
1aae0 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 ^If.** the table
1aaf0 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 has a column of
1ab00 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 type [INTEGER P
1ab10 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e RIMARY KEY] then
1ab20 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 that column.**
1ab30 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 is another alias
1ab40 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a for the rowid..
1ab50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1ab60 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
1ab70 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 owid(D) interfac
1ab80 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e e usually return
1ab90 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 s the [rowid] of
1aba0 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 .** the most rec
1abb0 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b ent successful [
1abc0 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 INSERT] into a r
1abd0 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 owid table or [v
1abe0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a irtual table].**
1abf0 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e on database con
1ac00 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 nection D. ^Inse
1ac10 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 rts into [WITHOU
1ac20 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 T ROWID] tables
1ac30 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 are not.** recor
1ac40 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 ded. ^If no succ
1ac50 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 essful [INSERT]s
1ac60 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c into rowid tabl
1ac70 65 73 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 es have ever occ
1ac80 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 urred .** on the
1ac90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1aca0 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c tion D, then sql
1acb0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
1acc0 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e _rowid(D) return
1acd0 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a s .** zero..**.*
1ace0 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69 * As well as bei
1acf0 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63 ng set automatic
1ad00 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65 ally as rows are
1ad10 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64 inserted into d
1ad20 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 atabase.** table
1ad30 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 s, the value ret
1ad40 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 urned by this fu
1ad50 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 nction may be se
1ad60 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a t explicitly by.
1ad70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f ** [sqlite3_set_
1ad80 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
1ad90 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 d()].**.** Some
1ada0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d virtual table im
1adb0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 plementations ma
1adc0 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e y INSERT rows in
1add0 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 to rowid tables
1ade0 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f as.** part of co
1adf0 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 mmitting a trans
1ae00 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 action (e.g. to
1ae10 66 6c 75 73 68 20 64 61 74 61 20 61 63 63 75 6d flush data accum
1ae20 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 ulated in memory
1ae30 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e .** to disk). In
1ae40 20 74 68 69 73 20 63 61 73 65 20 73 75 62 73 65 this case subse
1ae50 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 quent calls to t
1ae60 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 his function ret
1ae70 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a urn the rowid.**
1ae80 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
1ae90 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 these internal
1aea0 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e INSERT operation
1aeb0 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20 74 s, which leads t
1aec0 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 o .** unintuitiv
1aed0 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75 e results. Virtu
1aee0 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 al table impleme
1aef0 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f ntations that do
1af00 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a write to rowid.
1af10 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69 ** tables in thi
1af20 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20 s way can avoid
1af30 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 this problem by
1af40 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 restoring the or
1af50 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 iginal .** rowid
1af60 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 value using [sq
1af70 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 lite3_set_last_i
1af80 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 nsert_rowid()] b
1af90 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 efore returning
1afa0 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 .** control to t
1afb0 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e he user..**.** ^
1afc0 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 (If an [INSERT]
1afd0 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 occurs within a
1afe0 74 72 69 67 67 65 72 20 74 68 65 6e 20 74 68 69 trigger then thi
1aff0 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a s routine will .
1b000 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 ** return the [r
1b010 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 owid] of the ins
1b020 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e erted row as lon
1b030 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 g as the trigger
1b040 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e is .** running.
1b050 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 Once the trigge
1b060 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 r program ends,
1b070 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
1b080 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 ed .** by this r
1b090 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 outine reverts t
1b0a0 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 o what it was be
1b0b0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 fore the trigger
1b0c0 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a was fired.)^.**
1b0d0 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d .** ^An [INSERT]
1b0e0 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 that fails due
1b0f0 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 to a constraint
1b100 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 violation is not
1b110 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c a.** successful
1b120 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f [INSERT] and do
1b130 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
1b140 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
1b150 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 by this.** rout
1b160 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 ine. ^Thus INSE
1b170 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 RT OR FAIL, INSE
1b180 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e RT OR IGNORE, IN
1b190 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b SERT OR ROLLBACK
1b1a0 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 ,.** and INSERT
1b1b0 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f OR ABORT make no
1b1c0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 changes to the
1b1d0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
1b1e0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 this.** routine
1b1f0 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 when their inser
1b200 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 tion fails. ^(W
1b210 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 hen INSERT OR RE
1b220 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 PLACE.** encount
1b230 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 ers a constraint
1b240 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 violation, it d
1b250 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 oes not fail. T
1b260 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e he.** INSERT con
1b270 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 tinues to comple
1b280 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 tion after delet
1b290 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 ing rows that ca
1b2a0 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 used.** the cons
1b2b0 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 traint problem s
1b2c0 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c o INSERT OR REPL
1b2d0 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 ACE will always
1b2e0 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 change.** the re
1b2f0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
1b300 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a is interface.)^.
1b310 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 **.** ^For the p
1b320 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 urposes of this
1b330 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 routine, an [INS
1b340 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 ERT] is consider
1b350 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 ed to.** be succ
1b360 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 essful even if i
1b370 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c t is subsequentl
1b380 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a y rolled back..*
1b390 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
1b3a0 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 on is accessible
1b3b0 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e to SQL statemen
1b3c0 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c ts via the.** [l
1b3d0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
1b3e0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d () SQL function]
1b3f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 ..**.** If a sep
1b400 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 arate thread per
1b410 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 forms a new [INS
1b420 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 ERT] on the same
1b430 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
1b440 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 nection while th
1b450 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f e [sqlite3_last_
1b460 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a insert_rowid()].
1b470 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 ** function is r
1b480 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 unning and thus
1b490 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 changes the last
1b4a0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c insert [rowid],
1b4b0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c .** then the val
1b4c0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b ue returned by [
1b4d0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
1b4e0 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a ert_rowid()] is.
1b4f0 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 ** unpredictable
1b500 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 and might not e
1b510 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 qual either the
1b520 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a old or the new.*
1b530 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 * last insert [r
1b540 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 owid]..*/.sqlite
1b550 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
1b560 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
1b570 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a d(sqlite3*);../*
1b580 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 .** CAPI3REF: Se
1b590 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72 t the Last Inser
1b5a0 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a t Rowid value..*
1b5b0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
1b5c0 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 3.**.** The sqli
1b5d0 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 te3_set_last_ins
1b5e0 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 ert_rowid(D, R)
1b5f0 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 method allows th
1b600 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f e application to
1b610 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75 .** set the valu
1b620 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 63 61 e returned by ca
1b630 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 lling sqlite3_la
1b640 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
1b650 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 D) to R .** with
1b660 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20 out inserting a
1b670 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74 row into the dat
1b680 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 abase..*/.void s
1b690 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f qlite3_set_last_
1b6a0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c insert_rowid(sql
1b6b0 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e ite3*,sqlite3_in
1b6c0 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 t64);../*.** CAP
1b6d0 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 I3REF: Count The
1b6e0 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 Number Of Rows
1b6f0 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 Modified.** METH
1b700 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
1b710 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
1b720 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
1b730 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 ber of rows modi
1b740 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f fied, inserted o
1b750 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 r.** deleted by
1b760 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c the most recentl
1b770 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 y completed INSE
1b780 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 RT, UPDATE or DE
1b790 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e LETE.** statemen
1b7a0 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 t on the databas
1b7b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 e connection spe
1b7c0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e cified by the on
1b7d0 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a ly parameter..**
1b7e0 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 ^Executing any
1b7f0 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 other type of SQ
1b800 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 L statement does
1b810 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 not modify the
1b820 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 value.** returne
1b830 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 d by this functi
1b840 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 on..**.** ^Only
1b850 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 changes made dir
1b860 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 ectly by the INS
1b870 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 ERT, UPDATE or D
1b880 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 ELETE statement
1b890 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 are.** considere
1b8a0 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 d - auxiliary ch
1b8b0 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 anges caused by
1b8c0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 [CREATE TRIGGER
1b8d0 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a | triggers], .**
1b8e0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 [foreign key ac
1b8f0 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 tions] or [REPLA
1b900 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 CE] constraint r
1b910 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f esolution are no
1b920 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a t counted..** .*
1b930 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 * Changes to a v
1b940 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 iew that are int
1b950 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 ercepted by .**
1b960 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 [INSTEAD OF trig
1b970 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 ger | INSTEAD OF
1b980 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e triggers] are n
1b990 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 ot counted. ^The
1b9a0 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 value .** retur
1b9b0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
1b9c0 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 hanges() immedia
1b9d0 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e tely after an IN
1b9e0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 SERT, UPDATE or
1b9f0 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 .** DELETE state
1ba00 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 ment run on a vi
1ba10 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 ew is always zer
1ba20 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 o. Only changes
1ba30 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a made to real .**
1ba40 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e tables are coun
1ba50 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 ted..**.** Thing
1ba60 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c s are more compl
1ba70 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 icated if the sq
1ba80 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 lite3_changes()
1ba90 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 function is.** e
1baa0 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 xecuted while a
1bab0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 trigger program
1bac0 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 is running. This
1bad0 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 may happen if t
1bae0 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 he.** program us
1baf0 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 es the [changes(
1bb00 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c ) SQL function],
1bb10 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 or if some othe
1bb20 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 r callback.** fu
1bb30 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 nction invokes s
1bb40 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
1bb50 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e directly. Essen
1bb60 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c tially:.** .** <
1bb70 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 ul>.** <li> ^(
1bb80 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 Before entering
1bb90 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 a trigger progra
1bba0 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 m the value retu
1bbb0 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 rned by.**
1bbc0 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 sqlite3_change
1bbd0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 s() function is
1bbe0 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 saved. After the
1bbf0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d trigger program
1bc00 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 .** has
1bc10 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 finished, the or
1bc20 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 iginal value is
1bc30 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a restored.)^.** .
1bc40 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 ** <li> ^(With
1bc50 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f in a trigger pro
1bc60 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 gram each INSERT
1bc70 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c , UPDATE and DEL
1bc80 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 ETE .** s
1bc90 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 tatement sets th
1bca0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
1bcb0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e by sqlite3_chan
1bcc0 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 ges() .**
1bcd0 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e upon completion
1bce0 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 as normal. Of c
1bcf0 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 ourse, this valu
1bd00 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 e will not inclu
1bd10 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e de .** an
1bd20 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 y changes perfor
1bd30 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 med by sub-trigg
1bd40 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 ers, as the sqli
1bd50 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a te3_changes() .*
1bd60 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 * value w
1bd70 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 ill be saved and
1bd80 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 restored after
1bd90 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 each sub-trigger
1bda0 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c has run.)^.** <
1bdb0 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 /ul>.** .** ^Thi
1bdc0 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 s means that if
1bdd0 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 the changes() SQ
1bde0 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 L function (or s
1bdf0 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a imilar) is used.
1be00 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ** by the first
1be10 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f INSERT, UPDATE o
1be20 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 r DELETE stateme
1be30 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 nt within a trig
1be40 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 ger, it .** retu
1be50 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 rns the value as
1be60 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 set when the ca
1be70 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 lling statement
1be80 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e began executing.
1be90 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 .** ^If it is us
1bea0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 ed by the second
1beb0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 or subsequent s
1bec0 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 uch statement wi
1bed0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a thin a trigger .
1bee0 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 ** program, the
1bef0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 value returned r
1bf00 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 eflects the numb
1bf10 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 er of rows modif
1bf20 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 ied by the .** p
1bf30 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 revious INSERT,
1bf40 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 UPDATE or DELETE
1bf50 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 statement withi
1bf60 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 n the same trigg
1bf70 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c er..**.** See al
1bf80 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f so the [sqlite3_
1bf90 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d total_changes()]
1bfa0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a interface, the.
1bfb0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 ** [count_change
1bfc0 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 s pragma], and t
1bfd0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 he [changes() SQ
1bfe0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a L function]..**.
1bff0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 ** If a separate
1c000 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 thread makes ch
1c010 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d anges on the sam
1c020 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
1c030 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b ction.** while [
1c040 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
1c050 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 )] is running th
1c060 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 en the value ret
1c070 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 urned.** is unpr
1c080 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f edictable and no
1c090 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f t meaningful..*/
1c0a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 .int sqlite3_cha
1c0b0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a nges(sqlite3*);.
1c0c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1c0d0 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 Total Number Of
1c0e0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a Rows Modified.*
1c0f0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
1c100 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 3.**.** ^This fu
1c110 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 nction returns t
1c120 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 he total number
1c130 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 of rows inserted
1c140 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a , modified or.**
1c150 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 deleted by all
1c160 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 [INSERT], [UPDAT
1c170 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 E] or [DELETE] s
1c180 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 tatements comple
1c190 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 ted.** since the
1c1a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1c1b0 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c tion was opened,
1c1c0 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 including those
1c1d0 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 executed as.**
1c1e0 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 part of trigger
1c1f0 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 programs. ^Execu
1c200 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 ting any other t
1c210 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 ype of SQL state
1c220 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 ment.** does not
1c230 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 affect the valu
1c240 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 e returned by sq
1c250 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
1c260 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 ges()..** .** ^C
1c270 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 hanges made as p
1c280 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 art of [foreign
1c290 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 key actions] are
1c2a0 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 included in the
1c2b0 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 .** count, but t
1c2c0 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 hose made as par
1c2d0 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e t of REPLACE con
1c2e0 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 straint resoluti
1c2f0 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e on are.** not. ^
1c300 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 Changes to a vie
1c310 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 w that are inter
1c320 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 cepted by INSTEA
1c330 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a D OF triggers .*
1c340 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 * are not counte
1c350 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c d..** .** See al
1c360 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f so the [sqlite3_
1c370 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 changes()] inter
1c380 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f face, the.** [co
1c390 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 unt_changes prag
1c3a0 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f ma], and the [to
1c3b0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 tal_changes() SQ
1c3c0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a L function]..**.
1c3d0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 ** If a separate
1c3e0 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 thread makes ch
1c3f0 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d anges on the sam
1c400 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
1c410 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b ction.** while [
1c420 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
1c430 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e anges()] is runn
1c440 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c ing then the val
1c450 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 ue.** returned i
1c460 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 s unpredictable
1c470 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 and not meaningf
1c480 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ul..*/.int sqlit
1c490 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
1c4a0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
1c4b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 ** CAPI3REF: Int
1c4c0 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 errupt A Long-Ru
1c4d0 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d nning Query.** M
1c4e0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
1c4f0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 *.** ^This funct
1c500 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 ion causes any p
1c510 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 ending database
1c520 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f operation to abo
1c530 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e rt and.** return
1c540 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 at its earliest
1c550 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 opportunity. Th
1c560 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 is routine is ty
1c570 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 pically.** calle
1c580 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f d in response to
1c590 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 a user action s
1c5a0 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 uch as pressing
1c5b0 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 "Cancel".** or C
1c5c0 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 trl-C where the
1c5d0 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e user wants a lon
1c5e0 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f g query operatio
1c5f0 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d n to halt.** imm
1c600 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ediately..**.**
1c610 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 ^It is safe to c
1c620 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 all this routine
1c630 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 from a thread d
1c640 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 ifferent from th
1c650 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 e.** thread that
1c660 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 is currently ru
1c670 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 nning the databa
1c680 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 se operation. B
1c690 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 ut it.** is not
1c6a0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 safe to call thi
1c6b0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 s routine with a
1c6c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1c6d0 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 ction] that.** i
1c6e0 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 s closed or migh
1c6f0 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 t close before s
1c700 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1c710 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a () returns..**.*
1c720 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 * ^If an SQL ope
1c730 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e ration is very n
1c740 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 early finished a
1c750 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a t the time when.
1c760 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 ** sqlite3_inter
1c770 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 rupt() is called
1c780 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 , then it might
1c790 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f not have an oppo
1c7a0 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 rtunity.** to be
1c7b0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 interrupted and
1c7c0 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 might continue
1c7d0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a to completion..*
1c7e0 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 *.** ^An SQL ope
1c7f0 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 ration that is i
1c800 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 nterrupted will
1c810 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 return [SQLITE_I
1c820 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 NTERRUPT]..** ^I
1c830 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 f the interrupte
1c840 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 d SQL operation
1c850 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 is an INSERT, UP
1c860 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a DATE, or DELETE.
1c870 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 ** that is insid
1c880 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 e an explicit tr
1c890 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 ansaction, then
1c8a0 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 the entire trans
1c8b0 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 action.** will b
1c8c0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 e rolled back au
1c8d0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a tomatically..**.
1c8e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1c8f0 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c interrupt(D) cal
1c900 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 l is in effect u
1c910 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 ntil all current
1c920 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 ly running.** SQ
1c930 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 L statements on
1c940 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1c950 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 tion] D complete
1c960 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 . ^Any new SQL
1c970 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 statements.** th
1c980 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 at are started a
1c990 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 fter the sqlite3
1c9a0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c _interrupt() cal
1c9b0 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 l and before the
1c9c0 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 .** running sta
1c9d0 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 tements reaches
1c9e0 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 zero are interru
1c9f0 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 pted as if they
1ca00 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e had been.** runn
1ca10 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 ing prior to the
1ca20 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
1ca30 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 pt() call. ^New
1ca40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
1ca50 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 ** that are star
1ca60 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 ted after the ru
1ca70 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 nning statement
1ca80 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 count reaches ze
1ca90 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 ro are.** not ef
1caa0 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 fected by the sq
1cab0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
1cac0 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f )..** ^A call to
1cad0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
1cae0 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 pt(D) that occur
1caf0 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 s when there are
1cb00 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 no running.** S
1cb10 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 QL statements is
1cb20 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 a no-op and has
1cb30 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 no effect on SQ
1cb40 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
1cb50 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 that are started
1cb60 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 after the sqlit
1cb70 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 e3_interrupt() c
1cb80 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a all returns..*/.
1cb90 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 void sqlite3_int
1cba0 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 errupt(sqlite3*)
1cbb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1cbc0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
1cbd0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
1cbe0 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a Is Complete.**.
1cbf0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
1cc00 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 s are useful dur
1cc10 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 ing command-line
1cc20 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d input to determ
1cc30 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 ine if the.** cu
1cc40 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 rrently entered
1cc50 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f text seems to fo
1cc60 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 rm a complete SQ
1cc70 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a L statement or.*
1cc80 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 * if additional
1cc90 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 input is needed
1cca0 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 before sending t
1ccb0 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 he text into.**
1ccc0 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 SQLite for parsi
1ccd0 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 ng. ^These rout
1cce0 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 ines return 1 if
1ccf0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e the input strin
1cd00 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 g.** appears to
1cd10 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 be a complete SQ
1cd20 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 L statement. ^A
1cd30 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 statement is ju
1cd40 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f dged to be.** co
1cd50 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 mplete if it end
1cd60 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c s with a semicol
1cd70 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 on token and is
1cd80 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 not a prefix of
1cd90 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 a.** well-formed
1cda0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 CREATE TRIGGER
1cdb0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d statement. ^Sem
1cdc0 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 icolons that are
1cdd0 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e embedded within
1cde0 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 .** string liter
1cdf0 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 als or quoted id
1ce00 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f entifier names o
1ce10 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e r comments are n
1ce20 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e ot.** independen
1ce30 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 t tokens (they a
1ce40 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 re part of the t
1ce50 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 oken in which th
1ce60 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 ey are.** embedd
1ce70 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 ed) and thus do
1ce80 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 not count as a s
1ce90 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 tatement termina
1cea0 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 tor. ^Whitespac
1ceb0 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 e.** and comment
1cec0 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 s that follow th
1ced0 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f e final semicolo
1cee0 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a n are ignored..*
1cef0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
1cf00 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 ines return 0 if
1cf10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
1cf20 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e s incomplete. ^
1cf30 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 If a.** memory a
1cf40 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c llocation fails,
1cf50 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d then SQLITE_NOM
1cf60 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a EM is returned..
1cf70 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
1cf80 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 tines do not par
1cf90 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 se the SQL state
1cfa0 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 ments thus.** wi
1cfb0 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 ll not detect sy
1cfc0 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f ntactically inco
1cfd0 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a rrect SQL..**.**
1cfe0 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 ^(If SQLite has
1cff0 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 not been initia
1d000 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c lized using [sql
1d010 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
1d020 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 )] prior .** to
1d030 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 invoking sqlite3
1d040 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 _complete16() th
1d050 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 en sqlite3_initi
1d060 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
1d070 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 ed.** automatica
1d080 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 lly by sqlite3_c
1d090 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 omplete16(). If
1d0a0 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 that initializa
1d0b0 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 tion fails,.** t
1d0c0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 hen the return v
1d0d0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
1d0e0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 3_complete16() w
1d0f0 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a ill be non-zero.
1d100 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ** regardless of
1d110 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
1d120 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 the input SQL is
1d130 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a complete.)^.**.
1d140 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 ** The input to
1d150 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
1d160 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a e()] must be a z
1d170 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
1d180 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a * UTF-8 string..
1d190 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 **.** The input
1d1a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 to [sqlite3_comp
1d1b0 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 lete16()] must b
1d1c0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 e a zero-termina
1d1d0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 ted.** UTF-16 st
1d1e0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 ring in native b
1d1f0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e yte order..*/.in
1d200 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 t sqlite3_comple
1d210 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 te(const char *s
1d220 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ql);.int sqlite3
1d230 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 _complete16(cons
1d240 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f t void *sql);../
1d250 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
1d260 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 egister A Callba
1d270 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c ck To Handle SQL
1d280 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a ITE_BUSY Errors.
1d290 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 ** KEYWORDS: {bu
1d2a0 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 sy-handler callb
1d2b0 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c ack} {busy handl
1d2c0 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 er}.** METHOD: s
1d2d0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
1d2e0 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 e sqlite3_busy_h
1d2f0 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f andler(D,X,P) ro
1d300 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c utine sets a cal
1d310 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 lback function X
1d320 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 .** that might b
1d330 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 e invoked with a
1d340 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 rgument P whenev
1d350 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 er.** an attempt
1d360 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 is made to acce
1d370 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 ss a database ta
1d380 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 ble associated w
1d390 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 ith.** [database
1d3a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 connection] D w
1d3b0 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 hen another thre
1d3c0 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 ad.** or process
1d3d0 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c has the table l
1d3e0 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 ocked..** The sq
1d3f0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
1d400 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 er() interface i
1d410 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d s used to implem
1d420 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ent.** [sqlite3_
1d430 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 busy_timeout()]
1d440 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 and [PRAGMA busy
1d450 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a _timeout]..**.**
1d460 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 ^If the busy ca
1d470 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 llback is NULL,
1d480 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 then [SQLITE_BUS
1d490 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 Y].** is returne
1d4a0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 d immediately up
1d4b0 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 on encountering
1d4c0 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 the lock. ^If t
1d4d0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
1d4e0 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c .** is not NULL,
1d4f0 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 then the callba
1d500 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f ck might be invo
1d510 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 ked with two arg
1d520 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 uments..**.** ^T
1d530 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
1d540 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 t to the busy ha
1d550 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 ndler is a copy
1d560 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 of the void* poi
1d570 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 nter which.** is
1d580 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d the third argum
1d590 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ent to sqlite3_b
1d5a0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 usy_handler().
1d5b0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 ^The second argu
1d5c0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 ment to.** the b
1d5d0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c usy handler call
1d5e0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 back is the numb
1d5f0 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 er of times that
1d600 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
1d610 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e r has.** been in
1d620 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 voked previously
1d630 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f for the same lo
1d640 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 cking event. ^I
1d650 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 f the.** busy ca
1d660 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 llback returns 0
1d670 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 , then no additi
1d680 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 onal attempts ar
1d690 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 e made to.** acc
1d6a0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ess the database
1d6b0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 and [SQLITE_BUS
1d6c0 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a Y] is returned.*
1d6d0 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 * to the applica
1d6e0 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 tion..** ^If the
1d6f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
1d700 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e s non-zero, then
1d710 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 another attempt
1d720 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 .** is made to a
1d730 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 ccess the databa
1d740 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 se and the cycle
1d750 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 repeats..**.**
1d760 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 The presence of
1d770 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 a busy handler d
1d780 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 oes not guarante
1d790 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 e that it will b
1d7a0 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 e invoked.** whe
1d7b0 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 n there is lock
1d7c0 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 contention. ^If
1d7d0 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 SQLite determine
1d7e0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 s that invoking
1d7f0 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 the busy.** hand
1d800 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 ler could result
1d810 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 in a deadlock,
1d820 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 it will go ahead
1d830 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c and return [SQL
1d840 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 ITE_BUSY].** to
1d850 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
1d860 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b instead of invok
1d870 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 ing the .** busy
1d880 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e handler..** Con
1d890 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f sider a scenario
1d8a0 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 where one proce
1d8b0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 ss is holding a
1d8c0 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a read lock that.*
1d8d0 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 * it is trying t
1d8e0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 o promote to a r
1d8f0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 eserved lock and
1d900 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f .** a second pro
1d910 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 cess is holding
1d920 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 a reserved lock
1d930 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e that it is tryin
1d940 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 g.** to promote
1d950 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 to an exclusive
1d960 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 lock. The first
1d970 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 process cannot
1d980 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 proceed.** becau
1d990 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 se it is blocked
1d9a0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 by the second a
1d9b0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 nd the second pr
1d9c0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 ocess cannot.**
1d9d0 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 proceed because
1d9e0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 it is blocked by
1d9f0 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 the first. If
1da00 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a both processes.*
1da10 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 * invoke the bus
1da20 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 y handlers, neit
1da30 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e her will make an
1da40 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 y progress. The
1da50 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 refore,.** SQLit
1da60 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 e returns [SQLIT
1da70 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 E_BUSY] for the
1da80 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 first process, h
1da90 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a oping that this.
1daa0 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 ** will induce t
1dab0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 he first process
1dac0 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 to release its
1dad0 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c read lock and al
1dae0 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e low.** the secon
1daf0 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f d process to pro
1db00 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ceed..**.** ^The
1db10 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 default busy ca
1db20 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a llback is NULL..
1db30 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 **.** ^(There ca
1db40 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 n only be a sing
1db50 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 le busy handler
1db60 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 defined for each
1db70 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
1db80 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 nnection]. Sett
1db90 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 ing a new busy h
1dba0 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e andler clears an
1dbb0 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 y.** previously
1dbc0 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 set handler.)^
1dbd0 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 ^Note that calli
1dbe0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 ng [sqlite3_busy
1dbf0 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f _timeout()].** o
1dc00 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 r evaluating [PR
1dc10 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 AGMA busy_timeou
1dc20 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 t=N] will change
1dc30 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e the.** busy han
1dc40 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c dler and thus cl
1dc50 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 ear any previous
1dc60 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 ly set busy hand
1dc70 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 ler..**.** The b
1dc80 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f usy callback sho
1dc90 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 uld not take any
1dca0 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d actions which m
1dcb0 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 odify the.** dat
1dcc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1dcd0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
1dce0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 e busy handler.
1dcf0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
1dd00 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e .** the busy han
1dd10 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e dler is not reen
1dd20 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 trant. Any such
1dd30 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 actions.** resu
1dd40 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 lt in undefined
1dd50 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a behavior..** .**
1dd60 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 A busy handler
1dd70 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 must not close t
1dd80 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1dd90 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 ection.** or [pr
1dda0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1ddb0 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 ] that invoked t
1ddc0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e he busy handler.
1ddd0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
1dde0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c busy_handler(sql
1ddf0 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 ite3*,int(*)(voi
1de00 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a d*,int),void*);.
1de10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1de20 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 Set A Busy Time
1de30 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 out.** METHOD: s
1de40 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
1de50 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 is routine sets
1de60 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f a [sqlite3_busy_
1de70 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 handler | busy h
1de80 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 andler] that sle
1de90 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 eps.** for a spe
1dea0 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 cified amount of
1deb0 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 time when a tab
1dec0 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e le is locked. ^
1ded0 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 The handler.** w
1dee0 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 ill sleep multip
1def0 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 le times until a
1df00 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c t least "ms" mil
1df10 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 liseconds of sle
1df20 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 eping.** have ac
1df30 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 cumulated. ^Aft
1df40 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 er at least "ms"
1df50 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 milliseconds of
1df60 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 sleeping,.** th
1df70 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e e handler return
1df80 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 s 0 which causes
1df90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1dfa0 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b ] to return.** [
1dfb0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a SQLITE_BUSY]..**
1dfc0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 .** ^Calling thi
1dfd0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 s routine with a
1dfe0 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 n argument less
1dff0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f than or equal to
1e000 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f zero.** turns o
1e010 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 ff all busy hand
1e020 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 lers..**.** ^(Th
1e030 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ere can only be
1e040 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 a single busy ha
1e050 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 ndler for a part
1e060 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
1e070 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1e080 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d at any given mom
1e090 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 ent. If another
1e0a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a busy handler.**
1e0b0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 was defined (u
1e0c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 sing [sqlite3_bu
1e0d0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 sy_handler()]) p
1e0e0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a rior to calling.
1e0f0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c ** this routine,
1e100 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 that other busy
1e110 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 handler is clea
1e120 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 red.)^.**.** See
1e130 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 also: [PRAGMA
1e140 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f busy_timeout].*/
1e150 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 .int sqlite3_bus
1e160 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 y_timeout(sqlite
1e170 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 3*, int ms);../*
1e180 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
1e190 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e nvenience Routin
1e1a0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 es For Running Q
1e1b0 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 ueries.** METHOD
1e1c0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
1e1d0 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 This is a legacy
1e1e0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 interface that
1e1f0 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 is preserved for
1e200 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
1e210 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 tibility..** Use
1e220 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 of this interfa
1e230 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d ce is not recomm
1e240 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 ended..**.** Def
1e250 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 inition: A <b>re
1e260 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 sult table</b> i
1e270 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 s memory data st
1e280 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 ructure created
1e290 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 by the.** [sqlit
1e2a0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 e3_get_table()]
1e2b0 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 interface. A re
1e2c0 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 sult table recor
1e2d0 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 ds the.** comple
1e2e0 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 te query results
1e2f0 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 from one or mor
1e300 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a e queries..**.**
1e310 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 The table conce
1e320 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 ptually has a nu
1e330 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 mber of rows and
1e340 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a columns. But.*
1e350 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 * these numbers
1e360 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 are not part of
1e370 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
1e380 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a itself. These.
1e390 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f ** numbers are o
1e3a0 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 btained separate
1e3b0 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 ly. Let N be th
1e3c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 e number of rows
1e3d0 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 .** and M be the
1e3e0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
1e3f0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 ns..**.** A resu
1e400 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 lt table is an a
1e410 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 rray of pointers
1e420 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 to zero-termina
1e430 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 ted UTF-8 string
1e440 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 s..** There are
1e450 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 (N+1)*M elements
1e460 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 in the array.
1e470 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e The first M poin
1e480 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f ters point.** to
1e490 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1e4a0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 strings that c
1e4b0 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 ontain the names
1e4c0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e of the columns.
1e4d0 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e .** The remainin
1e4e0 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f g entries all po
1e4f0 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 int to query res
1e500 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 ults. NULL valu
1e510 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 es result.** in
1e520 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 NULL pointers.
1e530 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 All other values
1e540 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 are in their UT
1e550 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 F-8 zero-termina
1e560 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 ted.** string re
1e570 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 presentation as
1e580 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
1e590 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
1e5a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 ()]..**.** A res
1e5b0 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 ult table might
1e5c0 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f consist of one o
1e5d0 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c r more memory al
1e5e0 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 locations..** It
1e5f0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
1e600 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 pass a result ta
1e610 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 ble directly to
1e620 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1e630 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 ..** A result ta
1e640 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 ble should be de
1e650 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 allocated using
1e660 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 [sqlite3_free_ta
1e670 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ble()]..**.** ^(
1e680 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 As an example of
1e690 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
1e6a0 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 e format, suppos
1e6b0 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 e a query result
1e6c0 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 .** is as follow
1e6d0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
1e6e0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 uote><pre>.**
1e6f0 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 Name
1e700 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 | Age.**
1e710 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ---------------
1e720 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 --------.**
1e730 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c Alice |
1e740 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 43.** Bo
1e750 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a b | 28.*
1e760 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 * Cindy
1e770 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 | 21.** </p
1e780 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1e790 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 .**.** There are
1e7a0 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d two column (M==
1e7b0 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 2) and three row
1e7c0 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 s (N==3). Thus
1e7d0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 the.** result ta
1e7e0 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 ble has 8 entrie
1e7f0 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 s. Suppose the
1e800 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 result table is
1e810 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 stored.** in an
1e820 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 array names azRe
1e830 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 sult. Then azRe
1e840 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 sult holds this
1e850 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c content:.**.** <
1e860 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1e870 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
1e880 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 ult[0] = "Na
1e890 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 me";.** a
1e8a0 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d zResult[1] =
1e8b0 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 "Age";.**
1e8c0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 azResult[2
1e8d0 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 ] = "Alice";.**
1e8e0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
1e8f0 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a #91;3] = "43";.*
1e900 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1e910 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 t[4] = "Bob"
1e920 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
1e930 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 sult[5] = "2
1e940 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 8";.** az
1e950 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 Result[6] =
1e960 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 "Cindy";.**
1e970 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1e980 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 7] = "21";.** </
1e990 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1e9a0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 >)^.**.** ^The s
1e9b0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
1e9c0 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c () function eval
1e9d0 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 uates one or mor
1e9e0 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 e.** semicolon-s
1e9f0 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 eparated SQL sta
1ea00 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a tements in the z
1ea10 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
1ea20 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f TF-8.** string o
1ea30 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 f its 2nd parame
1ea40 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ter and returns
1ea50 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 a result table t
1ea60 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 o the.** pointer
1ea70 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 given in its 3r
1ea80 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a d parameter..**.
1ea90 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 ** After the app
1eaa0 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e lication has fin
1eab0 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 ished with the r
1eac0 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 esult from sqlit
1ead0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a e3_get_table(),.
1eae0 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 ** it must pass
1eaf0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
1eb00 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 pointer to sqli
1eb10 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
1eb20 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 in order to.**
1eb30 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f release the memo
1eb40 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c ry that was mall
1eb50 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f oced. Because o
1eb60 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a f the way the.**
1eb70 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1eb80 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 ()] happens with
1eb90 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 in sqlite3_get_t
1eba0 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c able(), the call
1ebb0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ing.** function
1ebc0 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 must not try to
1ebd0 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 call [sqlite3_fr
1ebe0 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 ee()] directly.
1ebf0 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 Only.** [sqlite
1ec00 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 3_free_table()]
1ec10 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 is able to relea
1ec20 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 se the memory pr
1ec30 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c operly and safel
1ec40 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c y..**.** The sql
1ec50 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
1ec60 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d interface is im
1ec70 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 plemented as a w
1ec80 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a rapper around.**
1ec90 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
1eca0 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f ]. The sqlite3_
1ecb0 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 get_table() rout
1ecc0 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 ine does not hav
1ecd0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 e access.** to a
1ece0 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 ny internal data
1ecf0 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 structures of S
1ed00 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 QLite. It uses
1ed10 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a only the public.
1ed20 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 ** interface def
1ed30 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 ined here. As a
1ed40 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 consequence, er
1ed50 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 rors that occur
1ed60 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 in the.** wrappe
1ed70 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 r layer outside
1ed80 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 of the internal
1ed90 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
1eda0 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a call are not.**
1edb0 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 reflected in su
1edc0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
1edd0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f o [sqlite3_errco
1ede0 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c de()] or.** [sql
1edf0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a ite3_errmsg()]..
1ee00 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 */.int sqlite3_g
1ee10 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 et_table(. sqli
1ee20 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
1ee30 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 /* An open dat
1ee40 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 abase */. const
1ee50 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 char *zSql,
1ee60 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 /* SQL to be ev
1ee70 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 aluated */. cha
1ee80 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 r ***pazResult,
1ee90 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 /* Results of
1eea0 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 the query */.
1eeb0 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 int *pnRow,
1eec0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 /* Number
1eed0 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 of result rows w
1eee0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 ritten here */.
1eef0 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 int *pnColumn,
1ef00 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 /* Number
1ef10 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d of result colum
1ef20 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 ns written here
1ef30 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 */. char **pzEr
1ef40 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 rmsg /* Er
1ef50 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 ror msg written
1ef60 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 here */.);.void
1ef70 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
1ef80 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 le(char **result
1ef90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1efa0 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 EF: Formatted St
1efb0 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 ring Printing Fu
1efc0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 nctions.**.** Th
1efd0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
1efe0 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 work-alikes of
1eff0 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 the "printf()" f
1f000 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f amily of functio
1f010 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 ns.** from the s
1f020 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
1f030 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 y..** These rout
1f040 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 ines understand
1f050 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d most of the comm
1f060 6f 6e 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 on formatting op
1f070 74 69 6f 6e 73 20 66 72 6f 6d 0a 2a 2a 20 74 68 tions from.** th
1f080 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 e standard libra
1f090 72 79 20 70 72 69 6e 74 66 28 29 20 0a 2a 2a 20 ry printf() .**
1f0a0 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 plus some additi
1f0b0 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 onal non-standar
1f0c0 64 20 66 6f 72 6d 61 74 73 20 28 5b 25 71 5d 2c d formats ([%q],
1f0d0 20 5b 25 51 5d 2c 20 5b 25 77 5d 2c 20 61 6e 64 [%Q], [%w], and
1f0e0 20 5b 25 7a 5d 29 2e 0a 2a 2a 20 53 65 65 20 74 [%z])..** See t
1f0f0 68 65 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69 he [built-in pri
1f100 6e 74 66 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 ntf()] documenta
1f110 74 69 6f 6e 20 66 6f 72 20 64 65 74 61 69 6c 73 tion for details
1f120 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
1f130 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 ite3_mprintf() a
1f140 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 nd sqlite3_vmpri
1f150 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 ntf() routines w
1f160 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 rite their.** re
1f170 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 sults into memor
1f180 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
1f190 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 [sqlite3_malloc6
1f1a0 34 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 4()]..** The str
1f1b0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 ings returned by
1f1c0 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 these two routi
1f1d0 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a nes should be.**
1f1e0 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 released by [sq
1f1f0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 lite3_free()].
1f200 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 ^Both routines r
1f210 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 eturn a.** NULL
1f220 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 pointer if [sqli
1f230 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 20 te3_malloc64()]
1f240 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c is unable to all
1f250 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 ocate enough.**
1f260 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 memory to hold t
1f270 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 he resulting str
1f280 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ing..**.** ^(The
1f290 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
1f2a0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 f() routine is s
1f2b0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 imilar to "snpri
1f2c0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 ntf()" from.** t
1f2d0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 he standard C li
1f2e0 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 brary. The resu
1f2f0 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e lt is written in
1f300 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 to the.** buffer
1f310 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 supplied as the
1f320 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
1f330 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 r whose size is
1f340 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 given by.** the
1f350 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e first parameter.
1f360 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f Note that the o
1f370 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 rder of the.** f
1f380 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 irst two paramet
1f390 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 ers is reversed
1f3a0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e from snprintf().
1f3b0 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a )^ This is an.*
1f3c0 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 * historical acc
1f3d0 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f ident that canno
1f3e0 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f t be fixed witho
1f3f0 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 ut breaking.** b
1f400 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
1f410 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 bility. ^(Note
1f420 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 also that sqlite
1f430 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
1f440 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
1f450 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 r to its buffer
1f460 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e instead of the n
1f470 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 umber of.** char
1f480 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 acters actually
1f490 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 written into the
1f4a0 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 buffer.)^ We a
1f4b0 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 dmit that.** the
1f4c0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 number of chara
1f4d0 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f cters written wo
1f4e0 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 uld be a more us
1f4f0 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 eful return.** v
1f500 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e alue but we cann
1f510 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d ot change the im
1f520 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
1f530 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
1f540 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 ().** now withou
1f550 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 t breaking compa
1f560 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 tibility..**.**
1f570 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 ^As long as the
1f580 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 buffer size is g
1f590 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f reater than zero
1f5a0 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e , sqlite3_snprin
1f5b0 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 tf().** guarante
1f5c0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 es that the buff
1f5d0 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 er is always zer
1f5e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e o-terminated. ^
1f5f0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 The first.** par
1f600 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 ameter "n" is th
1f610 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 e total size of
1f620 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c the buffer, incl
1f630 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a uding space for.
1f640 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d ** the zero term
1f650 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 inator. So the
1f660 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 longest string t
1f670 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c hat can be compl
1f680 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e etely.** written
1f690 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 will be n-1 cha
1f6a0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e racters..**.** ^
1f6b0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 The sqlite3_vsnp
1f6c0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 rintf() routine
1f6d0 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 is a varargs ver
1f6e0 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f sion of sqlite3_
1f6f0 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a snprintf()..**.*
1f700 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 62 75 * See also: [bu
1f710 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d ilt-in printf()]
1f720 2c 20 5b 70 72 69 6e 74 66 28 29 20 53 51 4c 20 , [printf() SQL
1f730 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2f 0a 63 68 61 function].*/.cha
1f740 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e r *sqlite3_mprin
1f750 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e tf(const char*,.
1f760 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 ..);.char *sqlit
1f770 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 e3_vmprintf(cons
1f780 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 t char*, va_list
1f790 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 );.char *sqlite3
1f7a0 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 _snprintf(int,ch
1f7b0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
1f7c0 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c ...);.char *sql
1f7d0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 ite3_vsnprintf(i
1f7e0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 nt,char*,const c
1f7f0 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a har*, va_list);.
1f800 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1f810 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 Memory Allocati
1f820 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a on Subsystem.**.
1f830 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f ** The SQLite co
1f840 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 re uses these th
1f850 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 ree routines for
1f860 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a all of its own.
1f870 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f ** internal memo
1f880 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
1f890 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 eds. "Core" in t
1f8a0 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 he previous sent
1f8b0 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 ence.** does not
1f8c0 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 include operati
1f8d0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 ng-system specif
1f8e0 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 ic VFS implement
1f8f0 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 ation. The.** W
1f900 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 indows VFS uses
1f910 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 native malloc()
1f920 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 and free() for s
1f930 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a ome operations..
1f940 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1f950 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 e3_malloc() rout
1f960 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ine returns a po
1f970 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b inter to a block
1f980 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 .** of memory at
1f990 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 least N bytes i
1f9a0 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 n length, where
1f9b0 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 N is the paramet
1f9c0 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 er..** ^If sqlit
1f9d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 e3_malloc() is u
1f9e0 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 nable to obtain
1f9f0 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a sufficient free.
1fa00 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 ** memory, it re
1fa10 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
1fa20 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 nter. ^If the p
1fa30 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a arameter N to.**
1fa40 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1fa50 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 ) is zero or neg
1fa60 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 ative then sqlit
1fa70 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 e3_malloc() retu
1fa80 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f rns.** a NULL po
1fa90 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 inter..**.** ^Th
1faa0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 e sqlite3_malloc
1fab0 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 64(N) routine wo
1fac0 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a rks just like.**
1fad0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1fae0 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e N) except that N
1faf0 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 is an unsigned
1fb00 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 64-bit integer i
1fb10 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 nstead.** of a s
1fb20 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 igned 32-bit int
1fb30 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c eger..**.** ^Cal
1fb40 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 ling sqlite3_fre
1fb50 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 e() with a point
1fb60 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 er previously re
1fb70 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c turned.** by sql
1fb80 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 ite3_malloc() or
1fb90 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1fba0 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 () releases that
1fbb0 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 memory so.** th
1fbc0 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 at it might be r
1fbd0 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c eused. ^The sql
1fbe0 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 ite3_free() rout
1fbf0 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f ine is.** a no-o
1fc00 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 p if is called w
1fc10 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
1fc20 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e er. Passing a N
1fc30 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 ULL pointer.** t
1fc40 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 o sqlite3_free()
1fc50 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 is harmless. A
1fc60 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 fter being freed
1fc70 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 , memory.** shou
1fc80 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 ld neither be re
1fc90 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 ad nor written.
1fca0 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 Even reading pr
1fcb0 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a eviously freed.*
1fcc0 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 * memory might r
1fcd0 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 esult in a segme
1fce0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 ntation fault or
1fcf0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 other severe er
1fd00 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 ror..** Memory c
1fd10 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 orruption, a seg
1fd20 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c mentation fault,
1fd30 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 or other severe
1fd40 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 error.** might
1fd50 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 result if sqlite
1fd60 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 3_free() is call
1fd70 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 ed with a non-NU
1fd80 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a LL pointer that.
1fd90 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 ** was not obtai
1fda0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ned from sqlite3
1fdb0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c _malloc() or sql
1fdc0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
1fdd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1fde0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 e3_realloc(X,N)
1fdf0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
1fe00 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a ts to resize a.*
1fe10 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 * prior memory a
1fe20 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 llocation X to b
1fe30 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 e at least N byt
1fe40 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 es..** ^If the X
1fe50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
1fe60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c lite3_realloc(X,
1fe70 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 N).** is a NULL
1fe80 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 pointer then its
1fe90 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 behavior is ide
1fea0 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e ntical to callin
1feb0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c g.** sqlite3_mal
1fec0 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 loc(N)..** ^If t
1fed0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 he N parameter t
1fee0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
1fef0 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f c(X,N) is zero o
1ff00 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 r.** negative th
1ff10 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
1ff20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 is exactly the s
1ff30 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a ame as calling.*
1ff40 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 * sqlite3_free(X
1ff50 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 )..** ^sqlite3_r
1ff60 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 ealloc(X,N) retu
1ff70 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
1ff80 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
1ff90 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 tion.** of at le
1ffa0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 ast N bytes in s
1ffb0 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 ize or NULL if i
1ffc0 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f nsufficient memo
1ffd0 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e ry is available.
1ffe0 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 .** ^If M is the
1fff0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 size of the pri
20000 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 or allocation, t
20010 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 hen min(N,M) byt
20020 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 es.** of the pri
20030 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 or allocation ar
20040 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 e copied into th
20050 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 e beginning of b
20060 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a uffer returned.*
20070 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 * by sqlite3_rea
20080 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 lloc(X,N) and th
20090 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
200a0 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 on is freed..**
200b0 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c ^If sqlite3_real
200c0 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 loc(X,N) returns
200d0 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 NULL and N is p
200e0 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 ositive, then th
200f0 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 e.** prior alloc
20100 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 ation is not fre
20110 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
20120 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 qlite3_realloc64
20130 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 (X,N) interfaces
20140 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 works the same
20150 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 as.** sqlite3_re
20160 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 alloc(X,N) excep
20170 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 t that N is a 64
20180 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e -bit unsigned in
20190 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a teger instead.**
201a0 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 of a 32-bit sig
201b0 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a ned integer..**.
201c0 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 ** ^If X is a me
201d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
201e0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 previously obtai
201f0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ned from sqlite3
20200 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 _malloc(),.** sq
20210 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 lite3_malloc64()
20220 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f , sqlite3_reallo
20230 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f c(), or sqlite3_
20240 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 realloc64(), the
20250 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 n.** sqlite3_msi
20260 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 ze(X) returns th
20270 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d e size of that m
20280 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
20290 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 in bytes..** ^T
202a0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
202b0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 d by sqlite3_msi
202c0 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c ze(X) might be l
202d0 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e arger than the n
202e0 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 umber.** of byte
202f0 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e s requested when
20300 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 X was allocated
20310 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 . ^If X is a NU
20320 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a LL pointer then.
20330 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 ** sqlite3_msize
20340 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f (X) returns zero
20350 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 . If X points t
20360 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 o something that
20370 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 is not.** the b
20380 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f eginning of memo
20390 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f ry allocation, o
203a0 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 r if it points t
203b0 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 o a formerly.**
203c0 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c valid memory all
203d0 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 ocation that has
203e0 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c now been freed,
203f0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
20400 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 or.** of sqlite3
20410 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 _msize(X) is und
20420 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 efined and possi
20430 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a bly harmful..**.
20440 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 ** ^The memory r
20450 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
20460 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c e3_malloc(), sql
20470 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a ite3_realloc(),.
20480 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f ** sqlite3_mallo
20490 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 c64(), and sqlit
204a0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a e3_realloc64().*
204b0 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 * is always alig
204c0 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 ned to at least
204d0 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 an 8 byte bounda
204e0 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 ry, or to a.** 4
204f0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 byte boundary i
20500 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f f the [SQLITE_4_
20510 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c BYTE_ALIGNED_MAL
20520 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d LOC] compile-tim
20530 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 e.** option is u
20540 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 sed..**.** In SQ
20550 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
20560 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 .0 and 3.5.1, it
20570 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f was possible to
20580 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 define.** the S
20590 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 QLITE_OMIT_MEMOR
205a0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 Y_ALLOCATION whi
205b0 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 ch would cause t
205c0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 he built-in.** i
205d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
205e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
205f0 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 to be omitted.
20600 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a That capability.
20610 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 ** is no longer
20620 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 provided. Only
20630 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
20640 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 allocators can b
20650 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 e used..**.** Pr
20660 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 ior to SQLite ve
20670 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 rsion 3.7.10, th
20680 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 e Windows OS int
20690 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c erface layer cal
206a0 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 led.** the syste
206b0 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 m malloc() and f
206c0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 ree() directly w
206d0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a hen converting.*
206e0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 * filenames betw
206f0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e een the UTF-8 en
20700 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 coding used by S
20710 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 QLite.** and wha
20720 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 tever filename e
20730 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 ncoding is used
20740 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 by the particula
20750 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 r Windows.** ins
20760 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f tallation. Memo
20770 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 ry allocation er
20780 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 rors were detect
20790 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 ed, but.** they
207a0 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 were reported ba
207b0 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 ck as [SQLITE_CA
207c0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 NTOPEN] or.** [S
207d0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 QLITE_IOERR] rat
207e0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
207f0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 _NOMEM]..**.** T
20800 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d he pointer argum
20810 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 ents to [sqlite3
20820 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 _free()] and [sq
20830 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
20840 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 .** must be eith
20850 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 er NULL or else
20860 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 pointers obtaine
20870 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a d from a prior.*
20880 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 * invocation of
20890 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
208a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
208b0 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 ealloc()] that h
208c0 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 ave.** not yet b
208d0 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a een released..**
208e0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
208f0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 ion must not rea
20900 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 d or write any p
20910 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 art of.** a bloc
20920 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 k of memory afte
20930 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 r it has been re
20940 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 leased using.**
20950 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
20960 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
20970 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 lloc()]..*/.void
20980 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 *sqlite3_malloc
20990 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c (int);.void *sql
209a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 ite3_malloc64(sq
209b0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 lite3_uint64);.v
209c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 oid *sqlite3_rea
209d0 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 lloc(void*, int)
209e0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f ;.void *sqlite3_
209f0 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c realloc64(void*,
20a00 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 sqlite3_uint64)
20a10 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 ;.void sqlite3_f
20a20 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 ree(void*);.sqli
20a30 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 te3_uint64 sqlit
20a40 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b e3_msize(void*);
20a50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
20a60 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
20a70 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a or Statistics.**
20a80 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 .** SQLite provi
20a90 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e des these two in
20aa0 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 terfaces for rep
20ab0 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 orting on the st
20ac0 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b atus.** of the [
20ad0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
20ae0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ], [sqlite3_free
20af0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
20b00 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 3_realloc()].**
20b10 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 routines, which
20b20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 form the built-i
20b30 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
20b40 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a ion subsystem..*
20b50 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 *.** ^The [sqlit
20b60 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
20b70 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ] routine return
20b80 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
20b90 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f bytes.** of memo
20ba0 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 ry currently out
20bb0 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 standing (malloc
20bc0 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 ed but not freed
20bd0 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 )..** ^The [sqli
20be0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
20bf0 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 ater()] routine
20c00 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 returns the maxi
20c10 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 mum.** value of
20c20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
20c30 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 used()] since th
20c40 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 e high-water mar
20c50 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 k.** was last re
20c60 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 set. ^The value
20c70 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
20c80 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
20c90 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 ed()] and.** [sq
20ca0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
20cb0 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 hwater()] includ
20cc0 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a e any overhead.*
20cd0 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 * added by SQLit
20ce0 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 e in its impleme
20cf0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 ntation of [sqli
20d00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a te3_malloc()],.*
20d10 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 * but not overhe
20d20 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 ad added by the
20d30 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 any underlying s
20d40 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a ystem library.**
20d50 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b routines that [
20d60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
20d70 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a ] may call..**.*
20d80 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 * ^The memory hi
20d90 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 gh-water mark is
20da0 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 reset to the cu
20db0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a rrent value of.*
20dc0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 * [sqlite3_memor
20dd0 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 y_used()] if and
20de0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 only if the par
20df0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 ameter to.** [sq
20e00 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
20e10 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 hwater()] is tru
20e20 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 e. ^The value r
20e30 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 eturned.** by [s
20e40 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
20e50 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 ghwater(1)] is t
20e60 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 he high-water ma
20e70 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 rk.** prior to t
20e80 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c he reset..*/.sql
20e90 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
20ea0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 e3_memory_used(v
20eb0 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e oid);.sqlite3_in
20ec0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f t64 sqlite3_memo
20ed0 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 ry_highwater(int
20ee0 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a resetFlag);../*
20ef0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 .** CAPI3REF: Ps
20f00 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 eudo-Random Numb
20f10 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a er Generator.**.
20f20 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 ** SQLite contai
20f30 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 ns a high-qualit
20f40 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 y pseudo-random
20f50 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 number generator
20f60 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a (PRNG) used to.
20f70 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d ** select random
20f80 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 [ROWID | ROWIDs
20f90 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 ] when inserting
20fa0 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 new records int
20fb0 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a o a table that.*
20fc0 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 * already uses t
20fd0 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 he largest possi
20fe0 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 ble [ROWID]. Th
20ff0 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 e PRNG is also u
21000 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 sed for.** the b
21010 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 uild-in random()
21020 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 and randomblob(
21030 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e ) SQL functions.
21040 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 This interface
21050 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 allows.** appli
21060 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 cations to acces
21070 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 s the same PRNG
21080 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 for other purpos
21090 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c es..**.** ^A cal
210a0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e l to this routin
210b0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 e stores N bytes
210c0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 of randomness i
210d0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a nto buffer P..**
210e0 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 ^The P paramete
210f0 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 r can be a NULL
21100 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e pointer..**.** ^
21110 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 If this routine
21120 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 has not been pre
21130 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f viously called o
21140 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 r if the previou
21150 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 s.** call had N
21160 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 less than one or
21170 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
21180 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 for P, then the
21190 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 PRNG is.** seede
211a0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 d using randomne
211b0 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ss obtained from
211c0 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 the xRandomness
211d0 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 method of.** th
211e0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
211f0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a e3_vfs] object..
21200 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 ** ^If the previ
21210 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 ous call to this
21220 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 routine had an
21230 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 N of 1 or more a
21240 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c nd a.** non-NULL
21250 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 P then the pseu
21260 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 do-randomness is
21270 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e generated.** in
21280 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 ternally and wit
21290 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f hout recourse to
212a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
212b0 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a s] xRandomness.*
212c0 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 * method..*/.voi
212d0 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d d sqlite3_random
212e0 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 ness(int N, void
212f0 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *P);../*.** CAP
21300 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 I3REF: Compile-T
21310 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f ime Authorizatio
21320 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d n Callbacks.** M
21330 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
21340 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 * KEYWORDS: {aut
21350 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
21360 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f }.**.** ^This ro
21370 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 utine registers
21380 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 an authorizer ca
21390 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 llback with a pa
213a0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 rticular.** [dat
213b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
213c0 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 ], supplied in t
213d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
213e0 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f t..** ^The autho
213f0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
21400 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c s invoked as SQL
21410 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 statements are
21420 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a being compiled.*
21430 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 * by [sqlite3_pr
21440 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 epare()] or its
21450 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 variants [sqlite
21460 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 3_prepare_v2()],
21470 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
21480 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c pare_v3()], [sql
21490 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
214a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ], [sqlite3_prep
214b0 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 are16_v2()],.**
214c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
214d0 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e pare16_v3()]. ^
214e0 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f At various.** po
214f0 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 ints during the
21500 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 compilation proc
21510 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 ess, as logic is
21520 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a being created.*
21530 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 * to perform var
21540 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 ious actions, th
21550 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
21560 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
21570 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 to.** see if th
21580 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 ose actions are
21590 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 allowed. ^The a
215a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
215b0 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 ck should.** ret
215c0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
215d0 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 to allow the act
215e0 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e ion, [SQLITE_IGN
215f0 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 ORE] to disallow
21600 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 the.** specific
21610 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f action but allo
21620 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d w the SQL statem
21630 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 ent to continue
21640 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 to be.** compile
21650 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 d, or [SQLITE_DE
21660 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 NY] to cause the
21670 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 entire SQL stat
21680 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 ement to be.** r
21690 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 ejected with an
216a0 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 error. ^If the
216b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
216c0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 ack returns.** a
216d0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 ny value other t
216e0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f han [SQLITE_IGNO
216f0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d RE], [SQLITE_OK]
21700 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e , or [SQLITE_DEN
21710 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b Y].** then the [
21720 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
21730 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c v2()] or equival
21740 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 ent call that tr
21750 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 iggered.** the a
21760 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 uthorizer will f
21770 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f ail with an erro
21780 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a r message..**.**
21790 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 When the callba
217a0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
217b0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 TE_OK], that mea
217c0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e ns the operation
217d0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 .** requested is
217e0 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 ok. ^When the
217f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
21800 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 [SQLITE_DENY],
21810 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
21820 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
21830 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c equivalent call
21840 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 that triggered
21850 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 the.** authorize
21860 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 r will fail with
21870 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
21880 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 e explaining tha
21890 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 t.** access is d
218a0 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 enied. .**.** ^T
218b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
218c0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 er to the author
218d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
218e0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 a copy of the t
218f0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 hird.** paramete
21900 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
21910 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
21920 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 ) interface. ^Th
21930 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
21940 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c er.** to the cal
21950 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 lback is an inte
21960 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 ger [SQLITE_COPY
21970 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 | action code]
21980 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a that specifies.*
21990 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 * the particular
219a0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 action to be au
219b0 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 thorized. ^The t
219c0 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 hird through six
219d0 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a th parameters.**
219e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
219f0 20 61 72 65 20 65 69 74 68 65 72 20 4e 55 4c 4c are either NULL
21a00 20 70 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 pointers or zer
21a10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 o-terminated str
21a20 69 6e 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e ings.** that con
21a30 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 tain additional
21a40 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 details about th
21a50 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 e action to be a
21a60 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 uthorized..** Ap
21a70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 plications must
21a80 61 6c 77 61 79 73 20 62 65 20 70 72 65 70 61 72 always be prepar
21a90 65 64 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 ed to encounter
21aa0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
21ab0 6e 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 n any.** of the
21ac0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 74 68 third through th
21ad0 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 e sixth paramete
21ae0 72 73 20 6f 66 20 74 68 65 20 61 75 74 68 6f 72 rs of the author
21af0 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b ization callback
21b00 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
21b10 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b action code is [
21b20 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 SQLITE_READ].**
21b30 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b and the callback
21b40 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
21b50 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 _IGNORE] then th
21b60 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
21b70 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d tatement] statem
21b80 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 ent is construct
21b90 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 ed to substitute
21ba0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 .** a NULL value
21bb0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 in place of the
21bc0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 table column th
21bd0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a at would have.**
21be0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 been read if [S
21bf0 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 QLITE_OK] had be
21c00 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 en returned. Th
21c10 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 e [SQLITE_IGNORE
21c20 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 ].** return can
21c30 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 be used to deny
21c40 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 an untrusted use
21c50 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 r access to indi
21c60 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e vidual.** column
21c70 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a s of a table..**
21c80 20 5e 57 68 65 6e 20 61 20 74 61 62 6c 65 20 69 ^When a table i
21c90 73 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 s referenced by
21ca0 61 20 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 6e a [SELECT] but n
21cb0 6f 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 o column values
21cc0 61 72 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 are.** extracted
21cd0 20 66 72 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 from that table
21ce0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e (for example in
21cf0 20 61 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a a query like.**
21d00 20 22 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a "SELECT count(*
21d10 29 20 46 52 4f 4d 20 74 61 62 22 29 20 74 68 65 ) FROM tab") the
21d20 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 n the [SQLITE_RE
21d30 41 44 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 63 AD] authorizer c
21d40 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e allback.** is in
21d50 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 voked once for t
21d60 68 61 74 20 74 61 62 6c 65 20 77 69 74 68 20 61 hat table with a
21d70 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 column name tha
21d80 74 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 t is an empty st
21d90 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ring..** ^If the
21da0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 action code is
21db0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 [SQLITE_DELETE]
21dc0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b and the callback
21dd0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c returns.** [SQL
21de0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e ITE_IGNORE] then
21df0 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 the [DELETE] op
21e00 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 eration proceeds
21e10 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 but the.** [tru
21e20 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 ncate optimizati
21e30 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 on] is disabled
21e40 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 and all rows are
21e50 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 deleted individ
21e60 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 ually..**.** An
21e70 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 authorizer is us
21e80 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 ed when [sqlite3
21e90 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 _prepare | prepa
21ea0 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 ring].** SQL sta
21eb0 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 tements from an
21ec0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
21ed0 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 , to ensure that
21ee0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
21ef0 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 nts.** do not tr
21f00 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 y to access data
21f10 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c they are not al
21f20 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 lowed to see, or
21f30 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f that they do no
21f40 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 t.** try to exec
21f50 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 ute malicious st
21f60 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 atements that da
21f70 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 mage the databas
21f80 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 e. For.** examp
21f90 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 le, an applicati
21fa0 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 on may allow a u
21fb0 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 ser to enter arb
21fc0 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 itrary.** SQL qu
21fd0 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 eries for evalua
21fe0 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 tion by a databa
21ff0 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 se. But the app
22000 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a lication does.**
22010 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 not want the us
22020 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f er to be able to
22030 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 make arbitrary
22040 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a changes to the.*
22050 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 * database. An
22060 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 authorizer could
22070 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 then be put in
22080 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a place while the.
22090 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 ** user-entered
220a0 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 SQL is being [sq
220b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 lite3_prepare |
220c0 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a prepared] that.*
220d0 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 * disallows ever
220e0 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 ything except [S
220f0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
22100 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 s..**.** Applica
22110 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 tions that need
22120 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 to process SQL f
22130 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f rom untrusted so
22140 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 urces.** might a
22150 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 lso consider low
22160 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c ering resource l
22170 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c imits using [sql
22180 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a ite3_limit()].**
22190 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 and limiting da
221a0 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e tabase size usin
221b0 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f g the [max_page_
221c0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a count] [PRAGMA].
221d0 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 ** in addition t
221e0 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f o using an autho
221f0 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f rizer..**.** ^(O
22200 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 nly a single aut
22210 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 horizer can be i
22220 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 n place on a dat
22230 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
22240 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 .** at a time.
22250 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c Each call to sql
22260 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
22270 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 zer overrides th
22280 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 e.** previous ca
22290 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 ll.)^ ^Disable
222a0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 the authorizer b
222b0 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e y installing a N
222c0 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a ULL callback..**
222d0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 The authorizer
222e0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 is disabled by d
222f0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 efault..**.** Th
22300 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
22310 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 lback must not d
22320 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
22330 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
22340 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
22350 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
22360 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a ked the authoriz
22370 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 er callback..**
22380 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 Note that [sqlit
22390 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
223a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 and [sqlite3_st
223b0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 ep()] both modif
223c0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 y their.** datab
223d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
223e0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 for the meaning
223f0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 of "modify" in t
22400 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a his paragraph..*
22410 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 *.** ^When [sqli
22420 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
22430 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 ] is used to pre
22440 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 pare a statement
22450 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 , the.** stateme
22460 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 nt might be re-p
22470 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b repared during [
22480 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
22490 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 due to a .** sch
224a0 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e ema change. Hen
224b0 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 ce, the applicat
224c0 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 ion should ensur
224d0 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f e that the.** co
224e0 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 rrect authorizer
224f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e callback remain
22500 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e s in place durin
22510 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 g the [sqlite3_s
22520 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e tep()]..**.** ^N
22530 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 ote that the aut
22540 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
22550 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 is invoked only
22560 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 during.** [sqli
22570 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
22580 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 r its variants.
22590 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 Authorization i
225a0 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d s not.** perform
225b0 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d ed during statem
225c0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 ent evaluation i
225d0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 n [sqlite3_step(
225e0 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 )], unless.** as
225f0 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 stated in the p
22600 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 revious paragrap
22610 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 h, sqlite3_step(
22620 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c ) invokes.** sql
22630 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
22640 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 ) to reprepare a
22650 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 statement after
22660 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 a schema change
22670 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
22680 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
22690 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 . sqlite3*,. i
226a0 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 nt (*xAuth)(void
226b0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 *,int,const char
226c0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f *,const char*,co
226d0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
226e0 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a char*),. void *
226f0 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a pUserData.);../*
22700 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 .** CAPI3REF: Au
22710 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 thorizer Return
22720 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Codes.**.** The
22730 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
22740 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 horizer | author
22750 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 izer callback fu
22760 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 nction] must.**
22770 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 return either [S
22780 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 QLITE_OK] or one
22790 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f of these two co
227a0 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 nstants in order
227b0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 .** to signal SQ
227c0 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 Lite whether or
227d0 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 not the action i
227e0 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 s permitted. Se
227f0 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 e the.** [sqlite
22800 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
22810 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f | authorizer do
22820 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 cumentation] for
22830 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 additional.** i
22840 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
22850 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 * Note that SQLI
22860 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 TE_IGNORE is als
22870 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e o used as a [con
22880 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e flict resolution
22890 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e mode].** return
228a0 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c ed from the [sql
228b0 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e ite3_vtab_on_con
228c0 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 flict()] interfa
228d0 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ce..*/.#define S
228e0 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 QLITE_DENY 1
228f0 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 /* Abort the SQ
22900 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 L statement with
22910 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 an error */.#de
22920 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f fine SQLITE_IGNO
22930 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 RE 2 /* Don't
22940 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 allow access, bu
22950 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 t don't generate
22960 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a an error */../*
22970 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 .** CAPI3REF: Au
22980 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 thorizer Action
22990 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Codes.**.** The
229a0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
229b0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 horizer()] inter
229c0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 face registers a
229d0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
229e0 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e on.** that is in
229f0 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 voked to authori
22a00 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 ze certain SQL s
22a10 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 tatement actions
22a20 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 . The.** second
22a30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
22a40 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e e callback is an
22a50 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 integer code th
22a60 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 at specifies.**
22a70 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 what action is b
22a80 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e eing authorized.
22a90 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 These are the
22aa0 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 integer action c
22ab0 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 odes that.** the
22ac0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
22ad0 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 back may be pass
22ae0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ed..**.** These
22af0 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 action code valu
22b00 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 es signify what
22b10 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f kind of operatio
22b20 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 n is to be.** au
22b30 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 thorized. The 3
22b40 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d rd and 4th param
22b50 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 eters to the aut
22b60 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 horization.** ca
22b70 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
22b80 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 will be paramete
22b90 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e rs or NULL depen
22ba0 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 ding on which of
22bb0 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 these.** codes
22bc0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 is used as the s
22bd0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e econd parameter.
22be0 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 ^(The 5th para
22bf0 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 meter to the.**
22c00 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
22c10 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 ack is the name
22c20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
22c30 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c ("main", "temp",
22c40 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 .** etc.) if app
22c50 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 licable.)^ ^The
22c60 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6th parameter t
22c70 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 o the authorizer
22c80 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
22c90 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
22ca0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 inner-most trigg
22cb0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 er or view that
22cc0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
22cd0 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 or.** the access
22ce0 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c attempt or NULL
22cf0 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 if this access
22d00 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 attempt is direc
22d10 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d tly from.** top-
22d20 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a level SQL code..
22d30 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a */./************
22d40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
22d50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 ***************
22d60 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 3rd ************
22d70 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 4th ***********
22d80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22d90 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 _CREATE_INDEX
22da0 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 1 /* In
22db0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
22dc0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
22dd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22de0 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 CREATE_TABLE
22df0 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 2 /* Tab
22e00 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
22e10 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
22e20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
22e30 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 REATE_TEMP_INDEX
22e40 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 3 /* Inde
22e50 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
22e60 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
22e70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
22e80 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 EATE_TEMP_TABLE
22e90 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 4 /* Table
22ea0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
22eb0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
22ec0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
22ed0 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 ATE_TEMP_TRIGGER
22ee0 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 5 /* Trigge
22ef0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
22f00 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
22f10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
22f20 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 TE_TEMP_VIEW
22f30 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6 /* View Na
22f40 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
22f50 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
22f60 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
22f70 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 E_TRIGGER
22f80 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 7 /* Trigger
22f90 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
22fa0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
22fb0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
22fc0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 _VIEW
22fd0 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 8 /* View Name
22fe0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
22ff0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
23000 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 e SQLITE_DELETE
23010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 9
23020 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
23030 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
23040 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
23050 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 SQLITE_DROP_IND
23060 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 EX 10
23070 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
23080 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
23090 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
230a0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c SQLITE_DROP_TABL
230b0 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 E 11
230c0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
230d0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
230e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
230f0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
23100 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 INDEX 12
23110 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
23120 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
23130 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
23140 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 LITE_DROP_TEMP_T
23150 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f ABLE 13 /
23160 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
23170 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
23180 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
23190 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 ITE_DROP_TEMP_TR
231a0 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a IGGER 14 /*
231b0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
231c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
231d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
231e0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 TE_DROP_TEMP_VIE
231f0 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 W 15 /*
23200 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
23210 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
23220 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
23230 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 E_DROP_TRIGGER
23240 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 16 /* T
23250 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
23260 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
23270 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
23280 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 _DROP_VIEW
23290 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 17 /* Vi
232a0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
232b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
232c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
232d0 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 INSERT
232e0 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 18 /* Tab
232f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
23300 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
23310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 #define SQLITE_P
23320 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 RAGMA
23330 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 19 /* Prag
23340 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 ma Name 1st
23350 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 arg or NULL */.#
23360 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
23370 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AD
23380 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 /* Table
23390 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d Name Colum
233a0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 n Name */.#d
233b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c efine SQLITE_SEL
233c0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 ECT
233d0 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 21 /* NULL
233e0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 NULL
233f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
23400 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e fine SQLITE_TRAN
23410 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 SACTION
23420 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 22 /* Operati
23430 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 on NULL
23440 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
23450 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 ine SQLITE_UPDAT
23460 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
23470 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 23 /* Table Na
23480 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e me Column N
23490 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
234a0 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 ne SQLITE_ATTACH
234b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
234c0 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 4 /* Filename
234d0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
234e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
234f0 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 e SQLITE_DETACH
23500 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 25
23510 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e /* Database N
23520 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 ame NULL
23530 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
23540 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 SQLITE_ALTER_TA
23550 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 BLE 26
23560 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 /* Database Na
23570 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 me Table Name
23580 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
23590 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 SQLITE_REINDEX
235a0 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 27
235b0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
235c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
235d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
235e0 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 QLITE_ANALYZE
235f0 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 28
23600 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
23610 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
23620 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
23630 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 LITE_CREATE_VTAB
23640 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f LE 29 /
23650 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
23660 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 Module Name
23670 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
23680 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 ITE_DROP_VTABLE
23690 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 30 /*
236a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
236b0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 Module Name
236c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
236d0 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 TE_FUNCTION
236e0 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 31 /*
236f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
23700 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 Function Name
23710 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
23720 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 E_SAVEPOINT
23730 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 32 /* O
23740 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 peration S
23750 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a avepoint Name *
23760 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
23770 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 _COPY
23780 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 0 /* No
23790 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a longer used */.
237a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
237b0 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 ECURSIVE
237c0 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 33 /* NULL
237d0 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c NULL
237e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a */..
237f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
23800 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 Tracing And Prof
23810 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a iling Functions.
23820 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
23830 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 e3.**.** These r
23840 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 70 72 outines are depr
23850 65 63 61 74 65 64 2e 20 55 73 65 20 74 68 65 20 ecated. Use the
23860 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 [sqlite3_trace_v
23870 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2()] interface.*
23880 2a 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 * instead of the
23890 20 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 routines descri
238a0 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 bed here..**.**
238b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
238c0 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b egister callback
238d0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 functions that
238e0 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a can be used for.
238f0 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 ** tracing and p
23900 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 rofiling the exe
23910 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 cution of SQL st
23920 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
23930 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 ^The callback fu
23940 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
23950 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 d by sqlite3_tra
23960 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 ce() is invoked
23970 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 at.** various ti
23980 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 mes when an SQL
23990 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 statement is bei
239a0 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 ng run by [sqlit
239b0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e e3_step()]..** ^
239c0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 The sqlite3_trac
239d0 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 e() callback is
239e0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 invoked with a U
239f0 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f TF-8 rendering o
23a00 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 f the.** SQL sta
23a10 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 tement text as t
23a20 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 he statement fir
23a30 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 st begins execut
23a40 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 ing..** ^(Additi
23a50 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 onal sqlite3_tra
23a60 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d ce() callbacks m
23a70 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 ight occur.** as
23a80 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 each triggered
23a90 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e subprogram is en
23aa0 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c tered. The call
23ab0 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 backs for trigge
23ac0 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 rs.** contain a
23ad0 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e UTF-8 SQL commen
23ae0 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 t that identifie
23af0 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e s the trigger.)^
23b00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
23b10 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 TE_TRACE_SIZE_LI
23b20 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d MIT] compile-tim
23b30 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 e option can be
23b40 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a used to limit.**
23b50 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b the length of [
23b60 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d bound parameter]
23b70 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 expansion in th
23b80 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 e output of sqli
23b90 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a te3_trace()..**.
23ba0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b ** ^The callback
23bb0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 function regist
23bc0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ered by sqlite3_
23bd0 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 profile() is inv
23be0 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 oked.** as each
23bf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 SQL statement fi
23c00 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 nishes. ^The pr
23c10 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 ofile callback c
23c20 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f ontains.** the o
23c30 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e riginal statemen
23c40 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 t text and an es
23c50 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 timate of wall-c
23c60 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 lock time.** of
23c70 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 how long that st
23c80 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 atement took to
23c90 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 run. ^The profi
23ca0 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 le callback.** t
23cb0 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 ime is in units
23cc0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 of nanoseconds,
23cd0 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 however the curr
23ce0 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ent implementati
23cf0 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 on.** is only ca
23d00 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 pable of millise
23d10 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 cond resolution
23d20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 so the six least
23d30 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 significant.**
23d40 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 digits in the ti
23d50 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 me are meaningle
23d60 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 ss. Future vers
23d70 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a ions of SQLite.*
23d80 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 * might provide
23d90 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 greater resoluti
23da0 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c on on the profil
23db0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 er callback. Th
23dc0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f e.** sqlite3_pro
23dd0 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 file() function
23de0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 is considered ex
23df0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 perimental and i
23e00 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 s.** subject to
23e10 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 change in future
23e20 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
23e30 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 ite..*/.SQLITE_D
23e40 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a EPRECATED void *
23e50 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 sqlite3_trace(sq
23e60 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 lite3*,. void(
23e70 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 *xTrace)(void*,c
23e80 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 onst char*), voi
23e90 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 d*);.SQLITE_DEPR
23ea0 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c ECATED void *sql
23eb0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c ite3_profile(sql
23ec0 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a ite3*,. void(*
23ed0 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c xProfile)(void*,
23ee0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 const char*,sqli
23ef0 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 te3_uint64), voi
23f00 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
23f10 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 3REF: SQL Trace
23f20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b Event Codes.** K
23f30 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f EYWORDS: SQLITE_
23f40 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 TRACE.**.** Thes
23f50 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e e constants iden
23f60 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20 tify classes of
23f70 65 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20 events that can
23f80 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 be monitored.**
23f90 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 using the [sqlit
23fa0 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74 e3_trace_v2()] t
23fb0 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 racing logic. T
23fc0 68 65 20 4d 20 61 72 67 75 6d 65 6e 74 0a 2a 2a he M argument.**
23fd0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 to [sqlite3_tra
23fe0 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 5d 20 ce_v2(D,M,X,P)]
23ff0 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 is an OR-ed comb
24000 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f ination of one o
24010 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65 r more of.** the
24020 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 following const
24030 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69 72 73 ants. ^The firs
24040 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
24050 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b e trace callback
24060 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 .** is one of th
24070 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 e following cons
24080 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 tants..**.** New
24090 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e tracing constan
240a0 74 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ts may be added
240b0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
240c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 es..**.** ^A tra
240d0 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 20 ce callback has
240e0 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 four arguments:
240f0 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c xCallback(T,C,P,
24100 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 X)..** ^The T ar
24110 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 gument is one of
24120 20 74 68 65 20 69 6e 74 65 67 65 72 20 74 79 70 the integer typ
24130 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a e codes above..*
24140 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e * ^The C argumen
24150 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 t is a copy of t
24160 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 he context point
24170 65 72 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 er passed in as
24180 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 the.** fourth ar
24190 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 gument to [sqlit
241a0 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a e3_trace_v2()]..
241b0 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 ** The P and X a
241c0 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 rguments are poi
241d0 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e nters whose mean
241e0 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 ings depend on T
241f0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ..**.** <dl>.**
24200 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 [[SQLITE_TRACE_S
24210 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 TMT]] <dt>SQLITE
24220 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e _TRACE_STMT</dt>
24230 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 .** <dd>^An SQLI
24240 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 61 TE_TRACE_STMT ca
24250 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
24260 64 20 77 68 65 6e 20 61 20 70 72 65 70 61 72 65 d when a prepare
24270 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 d statement.** f
24280 69 72 73 74 20 62 65 67 69 6e 73 20 72 75 6e 6e irst begins runn
24290 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 ing and possibly
242a0 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65 73 20 at other times
242b0 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78 during the.** ex
242c0 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 70 ecution of the p
242d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
242e0 74 2c 20 73 75 63 68 20 61 73 20 61 74 20 74 68 t, such as at th
242f0 65 20 73 74 61 72 74 20 6f 66 20 65 61 63 68 0a e start of each.
24300 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62 70 72 ** trigger subpr
24310 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 72 ogram. ^The P ar
24320 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
24330 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 ter to the.** [p
24340 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
24350 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67 75 6d t]. ^The X argum
24360 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
24370 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 to a string whi
24380 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e 65 ch.** is the une
24390 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65 78 74 xpanded SQL text
243a0 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64 of the prepared
243b0 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e statement or an
243c0 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a SQL comment .**
243d0 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 that indicates
243e0 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f the invocation o
243f0 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 5e 54 f a trigger. ^T
24400 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 he callback can
24410 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 73 compute.** the s
24420 61 6d 65 20 74 65 78 74 20 74 68 61 74 20 77 6f ame text that wo
24430 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20 72 65 uld have been re
24440 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 6c 65 turned by the le
24450 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 gacy [sqlite3_tr
24460 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 ace()].** interf
24470 61 63 65 20 62 79 20 75 73 69 6e 67 20 74 68 65 ace by using the
24480 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e X argument when
24490 20 58 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 X begins with "
244a0 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 --" and invoking
244b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 70 .** [sqlite3_exp
244c0 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74 anded_sql(P)] ot
244d0 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b herwise..**.** [
244e0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 [SQLITE_TRACE_PR
244f0 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 OFILE]] <dt>SQLI
24500 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 TE_TRACE_PROFILE
24510 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e </dt>.** <dd>^An
24520 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 SQLITE_TRACE_PR
24530 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70 OFILE callback p
24540 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78 69 6d rovides approxim
24550 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a ately the same.*
24560 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 * information as
24570 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 is provided by
24580 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f the [sqlite3_pro
24590 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b file()] callback
245a0 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 ..** ^The P argu
245b0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
245c0 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 r to the [prepar
245d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e ed statement] an
245e0 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d d the.** X argum
245f0 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 ent points to a
24600 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 77 64-bit integer w
24610 68 69 63 68 20 69 73 20 74 68 65 20 65 73 74 69 hich is the esti
24620 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20 mated of.** the
24630 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 number of nanose
24640 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20 70 72 cond that the pr
24650 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
24660 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a took to run..**
24670 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54 52 41 ^The SQLITE_TRA
24680 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 CE_PROFILE callb
24690 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
246a0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e hen the statemen
246b0 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a t finishes..**.*
246c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 * [[SQLITE_TRACE
246d0 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 _ROW]] <dt>SQLIT
246e0 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e E_TRACE_ROW</dt>
246f0 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 .** <dd>^An SQLI
24700 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 6c TE_TRACE_ROW cal
24710 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
24720 20 77 68 65 6e 65 76 65 72 20 61 20 70 72 65 70 whenever a prep
24730 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e ared.** statemen
24740 74 20 67 65 6e 65 72 61 74 65 73 20 61 20 73 69 t generates a si
24750 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 75 ngle row of resu
24760 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20 lt. .** ^The P
24770 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f argument is a po
24780 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 inter to the [pr
24790 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
247a0 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 ] and the.** X a
247b0 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 rgument is unuse
247c0 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d..**.** [[SQLIT
247d0 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 E_TRACE_CLOSE]]
247e0 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 <dt>SQLITE_TRACE
247f0 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c _CLOSE</dt>.** <
24800 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 dd>^An SQLITE_TR
24810 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61 ACE_CLOSE callba
24820 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 ck is invoked wh
24830 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a en a database.**
24840 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 connection clos
24850 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 es..** ^The P ar
24860 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
24870 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 ter to the [data
24880 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
24890 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74 object.** and t
248a0 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 he X argument is
248b0 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c unused..** </dl
248c0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
248d0 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 20 ITE_TRACE_STMT
248e0 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69 6e 0x01.#defin
248f0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 e SQLITE_TRACE_P
24900 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32 0a 23 ROFILE 0x02.#
24910 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 define SQLITE_TR
24920 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20 20 30 ACE_ROW 0
24930 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 x04.#define SQLI
24940 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 20 TE_TRACE_CLOSE
24950 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 0x08../*.**
24960 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 CAPI3REF: SQL Tr
24970 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 ace Hook.** METH
24980 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
24990 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 * ^The sqlite3_t
249a0 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 race_v2(D,M,X,P)
249b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 interface regis
249c0 74 65 72 73 20 61 20 74 72 61 63 65 20 63 61 6c ters a trace cal
249d0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f lback.** functio
249e0 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64 61 74 n X against [dat
249f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
24a00 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 65 ] D, using prope
24a10 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e rty mask M.** an
24a20 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 d context pointe
24a30 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20 58 20 r P. ^If the X
24a40 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e callback is.** N
24a50 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20 4d 20 ULL or if the M
24a60 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68 mask is zero, th
24a70 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20 64 69 en tracing is di
24a80 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 sabled. The.**
24a90 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c M argument shoul
24aa0 64 20 62 65 20 74 68 65 20 62 69 74 77 69 73 65 d be the bitwise
24ab0 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 OR-ed combinati
24ac0 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 on of.** zero or
24ad0 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 52 more [SQLITE_TR
24ae0 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a ACE] constants..
24af0 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c **.** ^Each call
24b00 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c 69 74 to either sqlit
24b10 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 e3_trace() or sq
24b20 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 lite3_trace_v2()
24b30 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 28 overrides .** (
24b40 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 69 cancels) any pri
24b50 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 or calls to sqli
24b60 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 te3_trace() or s
24b70 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 qlite3_trace_v2(
24b80 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 )..**.** ^The X
24b90 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
24ba0 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 79 ked whenever any
24bb0 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73 20 69 of the events i
24bc0 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a 2a 2a dentified by .**
24bd0 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20 mask M occur.
24be0 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72 65 74 ^The integer ret
24bf0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 74 urn value from t
24c00 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 he callback is c
24c10 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f urrently.** igno
24c20 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68 69 73 red, though this
24c30 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e 20 66 may change in f
24c40 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20 uture releases.
24c50 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 Callback.** imp
24c60 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f lementations sho
24c70 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 uld return zero
24c80 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75 72 65 to ensure future
24c90 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a compatibility..
24ca0 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 **.** ^A trace c
24cb0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
24cc0 65 64 20 77 69 74 68 20 66 6f 75 72 20 61 72 67 ed with four arg
24cd0 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b uments: callback
24ce0 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 (T,C,P,X)..** ^T
24cf0 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 he T argument is
24d00 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 4c one of the [SQL
24d10 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f ITE_TRACE].** co
24d20 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 63 nstants to indic
24d30 61 74 65 20 77 68 79 20 74 68 65 20 63 61 6c 6c ate why the call
24d40 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64 back was invoked
24d50 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 ..** ^The C argu
24d60 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f ment is a copy o
24d70 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f f the context po
24d80 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20 inter..** The P
24d90 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 and X arguments
24da0 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f are pointers who
24db0 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 se meanings depe
24dc0 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 nd on T..**.** T
24dd0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 he sqlite3_trace
24de0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 _v2() interface
24df0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 72 is intended to r
24e00 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67 61 63 eplace the legac
24e10 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 y.** interfaces
24e20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 [sqlite3_trace()
24e30 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
24e40 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20 rofile()], both
24e50 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 20 of which.** are
24e60 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 69 deprecated..*/.i
24e70 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 nt sqlite3_trace
24e80 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c _v2(. sqlite3*,
24e90 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61 73 . unsigned uMas
24ea0 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62 k,. int(*xCallb
24eb0 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f ack)(unsigned,vo
24ec0 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 id*,void*,void*)
24ed0 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78 0a 29 ,. void *pCtx.)
24ee0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
24ef0 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 F: Query Progres
24f00 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d s Callbacks.** M
24f10 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
24f20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
24f30 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 3_progress_handl
24f40 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 er(D,N,X,P) inte
24f50 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 rface causes the
24f60 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e callback.** fun
24f70 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e ction X to be in
24f80 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c voked periodical
24f90 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 ly during long r
24fa0 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a unning calls to.
24fb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ** [sqlite3_exec
24fc0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 ()], [sqlite3_st
24fd0 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ep()] and [sqlit
24fe0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 e3_get_table()]
24ff0 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 for.** database
25000 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 connection D. A
25010 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f n example use fo
25020 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 r this.** interf
25030 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 ace is to keep a
25040 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 GUI updated dur
25050 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 ing a large quer
25060 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 y..**.** ^The pa
25070 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 rameter P is pas
25080 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 sed through as t
25090 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 he only paramete
250a0 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c r to the .** cal
250b0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 lback function X
250c0 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 . ^The paramete
250d0 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f r N is the appro
250e0 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 ximate number of
250f0 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 .** [virtual ma
25100 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f chine instructio
25110 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 ns] that are eva
25120 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 luated between s
25130 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 uccessive.** inv
25140 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ocations of the
25150 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 callback X. ^If
25160 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 N is less than
25170 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f one then the pro
25180 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 gress.** handler
25190 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a is disabled..**
251a0 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 .** ^Only a sing
251b0 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 le progress hand
251c0 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e ler may be defin
251d0 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 ed at one time p
251e0 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 er.** [database
251f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 connection]; set
25200 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 ting a new progr
25210 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 ess handler canc
25220 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f els the.** old o
25230 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 ne. ^Setting pa
25240 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c rameter X to NUL
25250 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 L disables the p
25260 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e rogress handler.
25270 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 .** ^The progres
25280 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 s handler is als
25290 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 o disabled by se
252a0 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c tting N to a val
252b0 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 ue less.** than
252c0 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 1..**.** ^If the
252d0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 progress callba
252e0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ck returns non-z
252f0 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 ero, the operati
25300 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 on is.** interru
25310 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 pted. This feat
25320 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ure can be used
25330 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a to implement a.*
25340 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f * "Cancel" butto
25350 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 n on a GUI progr
25360 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a ess dialog box..
25370 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 **.** The progre
25380 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 ss handler callb
25390 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ack must not do
253a0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
253b0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
253c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
253d0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
253e0 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 d the progress h
253f0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 andler..** Note
25400 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 that [sqlite3_pr
25410 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
25420 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
25430 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 both modify the
25440 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ir.** database c
25450 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
25460 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
25470 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
25480 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a aragraph..**.*/.
25490 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f void sqlite3_pro
254a0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 gress_handler(sq
254b0 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 lite3*, int, int
254c0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 (*)(void*), void
254d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
254e0 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e REF: Opening A N
254f0 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e ew Database Conn
25500 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 ection.** CONSTR
25510 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a UCTOR: sqlite3.*
25520 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
25530 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c ines open an SQL
25540 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c ite database fil
25550 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 e as specified b
25560 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 y the .** filena
25570 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 me argument. ^Th
25580 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d e filename argum
25590 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 ent is interpret
255a0 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a ed as UTF-8 for.
255b0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ** sqlite3_open(
255c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 ) and sqlite3_op
255d0 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 en_v2() and as U
255e0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 TF-16 in the nat
255f0 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 ive byte.** orde
25600 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 r for sqlite3_op
25610 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 en16(). ^(A [dat
25620 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
25630 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 ] handle is usua
25640 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lly.** returned
25650 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 in *ppDb, even i
25660 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 f an error occur
25670 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 s. The only exc
25680 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a eption is that.*
25690 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 * if SQLite is u
256a0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
256b0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 e memory to hold
256c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
256d0 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c bject,.** a NULL
256e0 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e will be written
256f0 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 into *ppDb inst
25700 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 ead of a pointer
25710 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
25720 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e ].** object.)^ ^
25730 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 (If the database
25740 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f is opened (and/
25750 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 or created) succ
25760 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a essfully, then.*
25770 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 * [SQLITE_OK] is
25780 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 returned. Othe
25790 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 rwise an [error
257a0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
257b0 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 d.)^ ^The.** [sq
257c0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 lite3_errmsg()]
257d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d or [sqlite3_errm
257e0 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 sg16()] routines
257f0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
25800 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 obtain.** an Eng
25810 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 lish language de
25820 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 scription of the
25830 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 error following
25840 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e a failure of an
25850 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 y.** of the sqli
25860 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 te3_open() routi
25870 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nes..**.** ^The
25880 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 default encoding
25890 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 will be UTF-8 f
258a0 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65 or databases cre
258b0 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 ated using.** sq
258c0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 lite3_open() or
258d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
258e0 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 ). ^The default
258f0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 encoding for da
25900 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 tabases.** creat
25910 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 ed using sqlite3
25920 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 _open16() will b
25930 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 e UTF-16 in the
25940 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
25950 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 r..**.** Whether
25960 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 or not an error
25970 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 occurs when it
25980 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 is opened, resou
25990 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 rces.** associat
259a0 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 ed with the [dat
259b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
259c0 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 ] handle should
259d0 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a be released by.*
259e0 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 * passing it to
259f0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
25a00 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 ] when it is no
25a10 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e longer required.
25a20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
25a30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 e3_open_v2() int
25a40 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b erface works lik
25a50 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 e sqlite3_open()
25a60 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 .** except that
25a70 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 it accepts two a
25a80 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 dditional parame
25a90 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f ters for additio
25aa0 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f nal control.** o
25ab0 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 ver the new data
25ac0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e base connection.
25ad0 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 ^(The flags pa
25ae0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 rameter to.** sq
25af0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
25b00 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a can take one of.
25b10 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ** the following
25b20 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f three values, o
25b30 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e ptionally combin
25b40 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 ed with the .**
25b50 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d [SQLITE_OPEN_NOM
25b60 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f UTEX], [SQLITE_O
25b70 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 PEN_FULLMUTEX],
25b80 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 [SQLITE_OPEN_SHA
25b90 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 REDCACHE],.** [S
25ba0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
25bb0 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 TECACHE], and/or
25bc0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 [SQLITE_OPEN_UR
25bd0 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a I] flags:)^.**.*
25be0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e * <dl>.** ^(<dt>
25bf0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
25c00 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c DONLY]</dt>.** <
25c10 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 dd>The database
25c20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 is opened in rea
25c30 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 d-only mode. If
25c40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f the database do
25c50 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 es not.** alread
25c60 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f y exist, an erro
25c70 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f r is returned.</
25c80 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 dd>)^.**.** ^(<d
25c90 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 t>[SQLITE_OPEN_R
25ca0 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a EADWRITE]</dt>.*
25cb0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 * <dd>The databa
25cc0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 se is opened for
25cd0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 reading and wri
25ce0 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 ting if possible
25cf0 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 , or reading.**
25d00 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 only if the file
25d10 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 is write protec
25d20 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 ted by the opera
25d30 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e ting system. In
25d40 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 either.** case
25d50 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 the database mus
25d60 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c t already exist,
25d70 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 otherwise an er
25d80 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ror is returned.
25d90 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 </dd>)^.**.** ^(
25da0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e <dt>[SQLITE_OPEN
25db0 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 _READWRITE] | [S
25dc0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
25dd0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 E]</dt>.** <dd>T
25de0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
25df0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e pened for readin
25e00 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 g and writing, a
25e10 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 nd is created if
25e20 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 .** it does not
25e30 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 already exist. T
25e40 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 his is the behav
25e50 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 ior that is alwa
25e60 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 ys used for.** s
25e70 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
25e80 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 d sqlite3_open16
25e90 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f ().</dd>)^.** </
25ea0 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 dl>.**.** If the
25eb0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
25ec0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
25ed0 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 2() is not one o
25ee0 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 f the.** combina
25ef0 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 tions shown abov
25f00 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d e optionally com
25f10 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 bined with other
25f20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
25f30 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 _READONLY | SQLI
25f40 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a TE_OPEN_* bits].
25f50 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 ** then the beha
25f60 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
25f70 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 d..**.** ^If the
25f80 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f [SQLITE_OPEN_NO
25f90 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 MUTEX] flag is s
25fa0 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 et, then the dat
25fb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
25fc0 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 .** opens in the
25fd0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 multi-thread [t
25fe0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 hreading mode] a
25ff0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 s long as the si
26000 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d ngle-thread.** m
26010 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e ode has not been
26020 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d set at compile-
26030 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 time or start-ti
26040 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 me. ^If the.**
26050 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c [SQLITE_OPEN_FUL
26060 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 LMUTEX] flag is
26070 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 set then the dat
26080 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
26090 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 opens.** in the
260a0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 serialized [thr
260b0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c eading mode] unl
260c0 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 ess single-threa
260d0 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 d was.** previou
260e0 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 sly selected at
260f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 compile-time or
26100 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e start-time..** ^
26110 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e The [SQLITE_OPEN
26120 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c _SHAREDCACHE] fl
26130 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 ag causes the da
26140 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
26150 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 n to be.** eligi
26160 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 ble to use [shar
26170 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 ed cache mode],
26180 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 regardless of wh
26190 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 ether or not sha
261a0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 red.** cache is
261b0 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 enabled using [s
261c0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 qlite3_enable_sh
261d0 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 ared_cache()].
261e0 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ^The.** [SQLITE_
261f0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
26200 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 E] flag causes t
26210 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
26220 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a ection to not.**
26230 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 participate in
26240 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f [shared cache mo
26250 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 de] even if it i
26260 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a s enabled..**.**
26270 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 ^The fourth par
26280 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
26290 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 3_open_v2() is t
262a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a he name of the.*
262b0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 * [sqlite3_vfs]
262c0 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 object that defi
262d0 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e nes the operatin
262e0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 g system interfa
262f0 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e ce that.** the n
26300 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
26310 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 ection should us
26320 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 e. ^If the four
26330 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a th parameter is.
26340 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ** a NULL pointe
26350 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 r then the defau
26360 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d lt [sqlite3_vfs]
26370 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e object is used.
26380 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .**.** ^If the f
26390 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d ilename is ":mem
263a0 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 ory:", then a pr
263b0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 ivate, temporary
263c0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 in-memory datab
263d0 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 ase.** is create
263e0 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 d for the connec
263f0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d tion. ^This in-
26400 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 memory database
26410 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e will vanish when
26420 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
26430 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
26440 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 losed. Future v
26450 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
26460 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 e might.** make
26470 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 use of additiona
26480 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 l special filena
26490 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 mes that begin w
264a0 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 ith the ":" char
264b0 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 acter..** It is
264c0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 recommended that
264d0 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 when a database
264e0 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c filename actual
264f0 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 ly does begin wi
26500 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 th.** a ":" char
26510 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 acter you should
26520 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 prefix the file
26530 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 name with a path
26540 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 name such as.**
26550 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d "./" to avoid am
26560 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e biguity..**.** ^
26570 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 If the filename
26580 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 is an empty stri
26590 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 ng, then a priva
265a0 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a te, temporary.**
265b0 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 on-disk databas
265c0 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 e will be create
265d0 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 d. ^This privat
265e0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 e database will
265f0 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 be.** automatica
26600 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 lly deleted as s
26610 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 oon as the datab
26620 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
26630 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 s closed..**.**
26640 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 [[URI filenames
26650 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 in sqlite3_open(
26660 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 )]] <h3>URI File
26670 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a names</h3>.**.**
26680 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 ^If [URI filena
26690 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 me] interpretati
266a0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 on is enabled, a
266b0 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 nd the filename
266c0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 argument.** begi
266d0 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c ns with "file:",
266e0 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 then the filena
266f0 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 me is interprete
26700 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 d as a URI. ^URI
26710 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 .** filename int
26720 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 erpretation is e
26730 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 nabled if the [S
26740 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 QLITE_OPEN_URI]
26750 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 flag is.** set i
26760 6e 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 n the third argu
26770 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
26780 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 open_v2(), or if
26790 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 it has.** been
267a0 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 enabled globally
267b0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 using the [SQLI
267c0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f TE_CONFIG_URI] o
267d0 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a ption with the.*
267e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
267f0 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 g()] method or b
26800 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 y the [SQLITE_US
26810 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 E_URI] compile-t
26820 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 55 ime option..** U
26830 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 RI filename inte
26840 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 rpretation is tu
26850 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 rned off.** by d
26860 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 efault, but futu
26870 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
26880 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 QLite might enab
26890 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a le URI filename.
268a0 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f ** interpretatio
268b0 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 n by default. S
268c0 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d ee "[URI filenam
268d0 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f es]" for additio
268e0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 nal.** informati
268f0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 on..**.** URI fi
26900 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 lenames are pars
26910 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 ed according to
26920 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 RFC 3986. ^If th
26930 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 e URI contains a
26940 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 n.** authority,
26950 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 then it must be
26960 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 either an empty
26970 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 string or the st
26980 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 ring .** "localh
26990 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 ost". ^If the au
269a0 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 thority is not a
269b0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f n empty string o
269c0 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 r "localhost", a
269d0 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 n .** error is r
269e0 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 eturned to the c
269f0 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 aller. ^The frag
26a00 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f ment component o
26a10 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 f a URI, if .**
26a20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f present, is igno
26a30 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 red..**.** ^SQLi
26a40 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 te uses the path
26a50 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 component of th
26a60 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d e URI as the nam
26a70 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 e of the disk fi
26a80 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 le.** which cont
26a90 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 ains the databas
26aa0 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 e. ^If the path
26ab0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f begins with a '/
26ac0 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a ' character, .**
26ad0 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 then it is inte
26ae0 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 rpreted as an ab
26af0 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 solute path. ^If
26b00 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e the path does n
26b10 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 ot begin .** wit
26b20 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 h a '/' (meaning
26b30 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 that the author
26b40 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f ity section is o
26b50 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 mitted from the
26b60 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 URI).** then the
26b70 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 path is interpr
26b80 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 eted as a relati
26b90 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f ve path. .** ^(O
26ba0 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 n windows, the f
26bb0 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f irst component o
26bc0 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 f an absolute pa
26bd0 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 th .** is a driv
26be0 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 e specification
26bf0 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a (e.g. "C:").)^.*
26c00 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 *.** [[core URI
26c10 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 query parameters
26c20 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 ]].** The query
26c30 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 component of a U
26c40 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 RI may contain p
26c50 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 arameters that a
26c60 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a re interpreted.*
26c70 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 * either by SQLi
26c80 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 te itself, or by
26c90 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d a [VFS | custom
26ca0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
26cb0 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 ion]..** SQLite
26cc0 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e and its built-in
26cd0 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 [VFSes] interpr
26ce0 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 et the.** follow
26cf0 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 ing query parame
26d00 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ters:.**.** <ul>
26d10 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 .** <li> <b>vf
26d20 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 s</b>: ^The "vfs
26d30 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 " parameter may
26d40 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 be used to speci
26d50 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a fy the name of.*
26d60 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 * a VFS obje
26d70 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 ct that provides
26d80 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
26d90 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 ystem interface
26da0 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 that should.**
26db0 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 be used to ac
26dc0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 cess the databas
26dd0 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 e file on disk.
26de0 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 ^If this option
26df0 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 is set to.**
26e00 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
26e10 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 the default VFS
26e20 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e object is used.
26e30 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 ^Specifying an
26e40 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 unknown.** V
26e50 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 FS is an error.
26e60 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ^If sqlite3_open
26e70 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e _v2() is used an
26e80 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e d the vfs option
26e90 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 is.** prese
26ea0 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 nt, then the VFS
26eb0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
26ec0 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 e option takes p
26ed0 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a recedence over.*
26ee0 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 * the value
26ef0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f passed as the fo
26f00 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
26f10 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
26f20 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 2()..**.** <li
26f30 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e > <b>mode</b>: ^
26f40 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 (The mode parame
26f50 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 ter may be set t
26f60 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 o either "ro", "
26f70 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 rw",.** "rwc
26f80 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 ", or "memory".
26f90 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 Attempting to se
26fa0 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 t it to any othe
26fb0 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 r value is.**
26fc0 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a an error)^. .*
26fd0 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 * ^If "ro" i
26fe0 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 s specified, the
26ff0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 n the database i
27000 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
27010 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 d-only .** a
27020 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 ccess, just as i
27030 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 f the [SQLITE_OP
27040 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 EN_READONLY] fla
27050 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 g had been set i
27060 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 n the .** th
27070 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ird argument to
27080 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
27090 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 ). ^If the mode
270a0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f option is set to
270b0 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 .** "rw", t
270c0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
270d0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
270e0 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e ead-write (but n
270f0 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 ot create) .**
27100 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 access, as if
27110 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 SQLITE_OPEN_REA
27120 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 DWRITE (but not
27130 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
27140 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 TE) had .**
27150 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 been set. ^Value
27160 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 "rwc" is equiva
27170 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 lent to setting
27180 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c both .** SQL
27190 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
271a0 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 TE and SQLITE_OP
271b0 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 EN_CREATE. ^If
271c0 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 the mode option
271d0 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f is.** set to
271e0 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 "memory" then a
271f0 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 pure [in-memory
27200 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 database] that
27210 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 never reads.**
27220 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f or writes fro
27230 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 m disk is used.
27240 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 ^It is an error
27250 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c to specify a val
27260 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 ue for.** th
27270 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 e mode parameter
27280 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 that is less re
27290 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 strictive than t
272a0 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 hat specified by
272b0 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 .** the flag
272c0 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 s passed in the
272d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
272e0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
272f0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c v2()..**.** <l
27300 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a i> <b>cache</b>:
27310 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 ^The cache para
27320 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 meter may be set
27330 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 to either "shar
27340 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 ed" or.** "p
27350 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e rivate". ^Settin
27360 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 g it to "shared"
27370 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 is equivalent t
27380 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a o setting the.**
27390 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e SQLITE_OPEN
273a0 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 _SHAREDCACHE bit
273b0 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 in the flags ar
273c0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f gument passed to
273d0 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f .** sqlite3_
273e0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 open_v2(). ^Sett
273f0 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 ing the cache pa
27400 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 rameter to "priv
27410 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 ate" is .**
27420 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 equivalent to se
27430 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 tting the SQLITE
27440 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 _OPEN_PRIVATECAC
27450 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e HE bit..** ^
27460 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f If sqlite3_open_
27470 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 v2() is used and
27480 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 the "cache" par
27490 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e ameter is presen
274a0 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 t in.** a UR
274b0 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 I filename, its
274c0 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 value overrides
274d0 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 any behavior req
274e0 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e uested by settin
274f0 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f g.** SQLITE_
27500 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
27510 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e E or SQLITE_OPEN
27520 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 _SHAREDCACHE fla
27530 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c g..**.** <li> <
27540 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 b>psow</b>: ^The
27550 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 psow parameter
27560 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65 indicates whethe
27570 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 r or not the.**
27580 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f [powersafe o
27590 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 verwrite] proper
275a0 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 ty does or does
275b0 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 not apply to the
275c0 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 .** storage
275d0 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 media on which t
275e0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
275f0 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 resides..**.**
27600 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c <li> <b>nolock<
27610 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b /b>: ^The nolock
27620 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
27630 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 boolean query pa
27640 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 rameter.** w
27650 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61 hich if set disa
27660 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e bles file lockin
27670 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f g in rollback jo
27680 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 urnal modes. Th
27690 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 is.** is use
276a0 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e ful for accessin
276b0 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 g a database on
276c0 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 a filesystem tha
276d0 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 t does not.**
276e0 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e support lockin
276f0 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 g. Caution: Da
27700 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f tabase corruptio
27710 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 n might result i
27720 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 f two.** or
27730 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 more processes w
27740 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 rite to the same
27750 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e database and an
27760 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a y one of those.*
27770 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 * processes
27780 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a uses nolock=1..*
27790 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d *.** <li> <b>im
277a0 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 mutable</b>: ^Th
277b0 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 e immutable para
277c0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 meter is a boole
277d0 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 an query.**
277e0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 parameter that i
277f0 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 ndicates that th
27800 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
27810 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 is stored on.**
27820 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 read-only me
27830 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 dia. ^When immu
27840 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 table is set, SQ
27850 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 Lite assumes tha
27860 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 t the.** dat
27870 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f abase file canno
27880 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 t be changed, ev
27890 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 en by a process
278a0 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 with higher.**
278b0 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e privilege, an
278c0 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 d so the databas
278d0 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 e is opened read
278e0 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f -only and all lo
278f0 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 cking.** and
27900 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f change detectio
27910 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 n is disabled.
27920 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 Caution: Setting
27930 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a the immutable.*
27940 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f * property o
27950 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c n a database fil
27960 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 e that does in f
27970 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 act change can r
27980 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 esult.** in
27990 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 incorrect query
279a0 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b results and/or [
279b0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 SQLITE_CORRUPT]
279c0 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 errors..** S
279d0 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 ee also: [SQLITE
279e0 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 _IOCAP_IMMUTABLE
279f0 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 ]..** .**
27a00 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 </ul>.**.** ^Spe
27a10 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f cifying an unkno
27a20 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 wn parameter in
27a30 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e the query compon
27a40 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 ent of a URI is
27a50 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e not an.** error.
27a60 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e Future version
27a70 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 s of SQLite migh
27a80 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 t understand add
27a90 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a itional query.**
27aa0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 parameters. Se
27ab0 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 e "[query parame
27ac0 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 ters with specia
27ad0 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c l meaning to SQL
27ae0 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 ite]" for.** add
27af0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
27b00 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 ion..**.** [[URI
27b10 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c filename exampl
27b20 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c es]] <h3>URI fil
27b30 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f ename examples</
27b40 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 h3>.**.** <table
27b50 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 border="1" alig
27b60 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 n=center cellpad
27b70 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c ding=5>.** <tr><
27b80 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 th> URI filename
27b90 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a s <th> Results.*
27ba0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a * <tr><td> file:
27bb0 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a data.db <td> .**
27bc0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 Open t
27bd0 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 he file "data.db
27be0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 " in the current
27bf0 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c directory..** <
27c00 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f tr><td> file:/ho
27c10 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c me/fred/data.db<
27c20 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 br>.**
27c30 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 file:///home/fre
27c40 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a d/data.db <br> .
27c50 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 ** file
27c60 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d ://localhost/hom
27c70 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c e/fred/data.db <
27c80 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 br> <td> .**
27c90 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 Open the d
27ca0 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 atabase file "/h
27cb0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
27cc0 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 "..** <tr><td> f
27cd0 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 ile://darkstar/h
27ce0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
27cf0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
27d00 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 An error. "da
27d10 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 rkstar" is not a
27d20 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 recognized auth
27d30 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 ority..** <tr><t
27d40 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 d style="white-s
27d50 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a pace:nowrap"> .*
27d60 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a * file:
27d70 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 ///C:/Documents%
27d80 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 20and%20Settings
27d90 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 /fred/Desktop/da
27da0 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 ta.db.** <td
27db0 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 > Windows only:
27dc0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 Open the file "d
27dd0 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 ata.db" on fred'
27de0 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 s desktop on dri
27df0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 ve.** C
27e00 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 :. Note that the
27e10 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e %20 escaping in
27e20 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 this example is
27e30 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a not strictly .*
27e40 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 * neces
27e50 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 sary - space cha
27e60 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 racters can be u
27e70 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a sed literally.**
27e80 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 in URI
27e90 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c filenames..** <
27ea0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 tr><td> file:dat
27eb0 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 a.db?mode=ro&cac
27ec0 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 he=private <td>
27ed0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 .** Ope
27ee0 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 n file "data.db"
27ef0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 in the current
27f00 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 directory for re
27f10 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a ad-only access..
27f20 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 ** Rega
27f30 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
27f40 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d r or not shared-
27f50 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e cache mode is en
27f60 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 abled by.**
27f70 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 default, us
27f80 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 e a private cach
27f90 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 e..** <tr><td> f
27fa0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 ile:/home/fred/d
27fb0 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d ata.db?vfs=unix-
27fc0 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 dotfile <td>.**
27fd0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 Open fi
27fe0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 le "/home/fred/d
27ff0 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 ata.db". Use the
28000 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e special VFS "un
28010 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 ix-dotfile".**
28020 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65 that use
28030 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 s dot-files in p
28040 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 lace of posix ad
28050 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a visory locking..
28060 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
28070 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 :data.db?mode=re
28080 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 adonly <td> .**
28090 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f An erro
280a0 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 r. "readonly" is
280b0 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 not a valid opt
280c0 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 ion for the "mod
280d0 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a e" parameter..**
280e0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 </table>.**.**
280f0 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c ^URI hexadecimal
28100 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 escape sequence
28110 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 s (%HH) are supp
28120 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 orted within the
28130 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 path and.** que
28140 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 ry components of
28150 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 a URI. A hexade
28160 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 cimal escape seq
28170 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f uence consists o
28180 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 f a.** percent s
28190 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c ign - "%" - foll
281a0 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 owed by exactly
281b0 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 two hexadecimal
281c0 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 digits .** speci
281d0 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 fying an octet v
281e0 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 alue. ^Before th
281f0 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 e path or query
28200 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a components of a.
28210 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 ** URI filename
28220 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c are interpreted,
28230 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 they are encode
28240 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e d using UTF-8 an
28250 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 d all .** hexade
28260 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 cimal escape seq
28270 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 uences replaced
28280 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 by a single byte
28290 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a containing the.
282a0 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 ** corresponding
282b0 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 octet. If this
282c0 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 process generate
282d0 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 s an invalid UTF
282e0 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 -8 encoding,.**
282f0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
28300 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
28310 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 <b>Note to Wind
28320 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 ows users:</b>
28330 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 The encoding use
28340 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 d for the filena
28350 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f me argument.** o
28360 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 f sqlite3_open()
28370 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
28380 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 n_v2() must be U
28390 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 TF-8, not whatev
283a0 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 er.** codepage i
283b0 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 s currently defi
283c0 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 ned. Filenames
283d0 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 containing inter
283e0 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 national.** char
283f0 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 acters must be c
28400 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d onverted to UTF-
28410 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 8 prior to passi
28420 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 ng them into.**
28430 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f sqlite3_open() o
28440 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
28450 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 2()..**.** <b>No
28460 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 te to Windows Ru
28470 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e ntime users:</b>
28480 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 The temporary
28490 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 directory must b
284a0 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 e set.** prior t
284b0 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 o calling sqlite
284c0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 3_open() or sqli
284d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 te3_open_v2().
284e0 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f Otherwise, vario
284f0 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 us.** features t
28500 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 hat require the
28510 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 use of temporary
28520 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e files may fail.
28530 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
28540 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 [sqlite3_temp_d
28550 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 irectory].*/.int
28560 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 sqlite3_open(.
28570 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c const char *fil
28580 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
28590 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
285a0 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 TF-8) */. sqlit
285b0 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 e3 **ppDb
285c0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 /* OUT: SQLit
285d0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 e db handle */.)
285e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 ;.int sqlite3_op
285f0 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f en16(. const vo
28600 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 id *filename,
28610 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
28620 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f name (UTF-16) */
28630 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 . sqlite3 **ppD
28640 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 b /* OU
28650 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e T: SQLite db han
28660 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 dle */.);.int sq
28670 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 lite3_open_v2(.
28680 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c const char *fil
28690 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
286a0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
286b0 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 TF-8) */. sqlit
286c0 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 e3 **ppDb,
286d0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 /* OUT: SQLit
286e0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 e db handle */.
286f0 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 int flags,
28700 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 /* Flag
28710 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 s */. const cha
28720 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f r *zVfs /
28730 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f * Name of VFS mo
28740 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 dule to use */.)
28750 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
28760 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 F: Obtain Values
28770 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 For URI Paramet
28780 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ers.**.** These
28790 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 are utility rout
287a0 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 ines, useful to
287b0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
287c0 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a ons, that check.
287d0 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 ** to see if a d
287e0 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 atabase file was
287f0 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 a URI that cont
28800 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 ained a specific
28810 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d query .** param
28820 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 eter, and if so
28830 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 obtains the valu
28840 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 e of that query
28850 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
28860 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 If F is the dat
28870 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 abase filename p
28880 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e ointer passed in
28890 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d to the xOpen() m
288a0 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 ethod of .** a V
288b0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
288c0 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 n when the flags
288d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f parameter to xO
288e0 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 pen() has one or
288f0 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 .** more of the
28900 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 [SQLITE_OPEN_UR
28910 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 I] or [SQLITE_OP
28920 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 EN_MAIN_DB] bits
28930 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 set and.** P is
28940 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
28950 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
28960 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 , then.** sqlite
28970 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 3_uri_parameter(
28980 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 F,P) returns the
28990 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a value of the P.
289a0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 ** parameter if
289b0 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e it exists or a N
289c0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 ULL pointer if P
289d0 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 does not appear
289e0 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 as a .** query
289f0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 parameter on F.
28a00 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 If P is a query
28a10 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a parameter of F.
28a20 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 ** has no explic
28a30 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 it value, then s
28a40 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d qlite3_uri_param
28a50 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e eter(F,P) return
28a60 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 s.** a pointer t
28a70 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e o an empty strin
28a80 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c g..**.** The sql
28a90 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e ite3_uri_boolean
28aa0 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 (F,P,B) routine
28ab0 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 assumes that P i
28ac0 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 s a boolean.** p
28ad0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 arameter and ret
28ae0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 urns true (1) or
28af0 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 false (0) accor
28b00 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 ding to the valu
28b10 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 e.** of P. The
28b20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c sqlite3_uri_bool
28b30 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 ean(F,P,B) routi
28b40 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 ne returns true
28b50 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 (1) if the.** va
28b60 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 lue of query par
28b70 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 ameter P is one
28b80 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 of "yes", "true"
28b90 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 , or "on" in any
28ba0 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 .** case or if t
28bb0 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 he value begins
28bc0 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 with a non-zero
28bd0 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a number. The .**
28be0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
28bf0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 lean(F,P,B) rout
28c00 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c ines returns fal
28c10 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 se (0) if the va
28c20 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 lue of.** query
28c30 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f parameter P is o
28c40 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c ne of "no", "fal
28c50 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e se", or "off" in
28c60 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 any case or.**
28c70 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 if the value beg
28c80 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 ins with a numer
28c90 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 ic zero. If P i
28ca0 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a s not a query.**
28cb0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 parameter on F
28cc0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 or if the value
28cd0 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 of P is does not
28ce0 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 match any of th
28cf0 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e e.** above, then
28d00 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
28d10 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 lean(F,P,B) retu
28d20 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a rns (B!=0)..**.*
28d30 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 * The sqlite3_ur
28d40 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 i_int64(F,P,D) r
28d50 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 outine converts
28d60 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 the value of P i
28d70 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 nto a.** 64-bit
28d80 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 signed integer a
28d90 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 nd returns that
28da0 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 integer, or D if
28db0 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 P does not.** e
28dc0 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 xist. If the va
28dd0 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 lue of P is some
28de0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e thing other than
28df0 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 an integer, the
28e00 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 n.** zero is ret
28e10 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 urned..** .** If
28e20 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 F is a NULL poi
28e30 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 nter, then sqlit
28e40 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 e3_uri_parameter
28e50 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 (F,P) returns NU
28e60 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 LL and.** sqlite
28e70 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 3_uri_boolean(F,
28e80 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 P,B) returns B.
28e90 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e If F is not a N
28ea0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a ULL pointer and.
28eb0 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 ** is not a data
28ec0 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 base file pathna
28ed0 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 me pointer that
28ee0 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e SQLite passed in
28ef0 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 to the xOpen.**
28f00 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e VFS method, then
28f10 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 the behavior of
28f20 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
28f30 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 undefined and p
28f40 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 robably.** undes
28f50 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 irable..*/.const
28f60 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 char *sqlite3_u
28f70 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e ri_parameter(con
28f80 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 st char *zFilena
28f90 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a me, const char *
28fa0 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c zParam);.int sql
28fb0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e ite3_uri_boolean
28fc0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 (const char *zFi
28fd0 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a le, const char *
28fe0 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 zParam, int bDef
28ff0 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 ault);.sqlite3_i
29000 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 nt64 sqlite3_uri
29010 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 _int64(const cha
29020 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c r*, const char*,
29030 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b sqlite3_int64);
29040 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
29050 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 F: Error Codes A
29060 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d nd Messages.** M
29070 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
29080 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 *.** ^If the mos
29090 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 t recent sqlite3
290a0 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f _* API call asso
290b0 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 ciated with .**
290c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
290d0 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 tion] D failed,
290e0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 then the sqlite3
290f0 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 _errcode(D) inte
29100 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 rface.** returns
29110 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 the numeric [re
29120 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 sult code] or [e
29130 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
29140 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a ode] for that.**
29150 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 API call..** If
29160 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
29170 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75 API call was su
29180 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 ccessful,.** the
29190 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c n the return val
291a0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
291b0 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 errcode() is und
291c0 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 efined..** ^The
291d0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
291e0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e _errcode().** in
291f0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 terface is the s
29200 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 ame except that
29210 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e it always return
29220 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e s the .** [exten
29230 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
29240 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e even when exten
29250 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
29260 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 are.** disabled
29270 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
29280 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e ite3_errmsg() an
29290 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 d sqlite3_errmsg
292a0 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 16() return Engl
292b0 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 ish-language.**
292c0 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 text that descri
292d0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 bes the error, a
292e0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f s either UTF-8 o
292f0 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 r UTF-16 respect
29300 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f ively..** ^(Memo
29310 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 ry to hold the e
29320 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 rror message str
29330 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 ing is managed i
29340 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 nternally..** Th
29350 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f e application do
29360 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 es not need to w
29370 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 orry about freei
29380 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a ng the result..*
29390 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 * However, the e
293a0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 rror string migh
293b0 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e t be overwritten
293c0 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 or deallocated
293d0 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 by.** subsequent
293e0 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 calls to other
293f0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
29400 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a functions.)^.**
29410 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
29420 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 _errstr() interf
29430 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
29440 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 English-language
29450 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 text.** that de
29460 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 scribes the [res
29470 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 ult code], as UT
29480 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 F-8..** ^(Memory
29490 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 to hold the err
294a0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e or message strin
294b0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 g is managed int
294c0 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d ernally.** and m
294d0 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 ust not be freed
294e0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 by the applicat
294f0 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 ion)^..**.** Whe
29500 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 n the serialized
29510 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
29520 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 ] is in use, it
29530 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 might be the.**
29540 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f case that a seco
29550 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 nd error occurs
29560 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 on a separate th
29570 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a read in between.
29580 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 ** the time of t
29590 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 he first error a
295a0 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 nd the call to t
295b0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e hese interfaces.
295c0 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 .** When that ha
295d0 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e ppens, the secon
295e0 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 d error will be
295f0 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 reported since t
29600 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 hese.** interfac
29610 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 es always report
29620 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
29630 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f result. To avo
29640 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 id.** this, each
29650 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 thread can obta
29660 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 in exclusive use
29670 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 of the [databas
29680 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a e connection] D.
29690 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b ** by invoking [
296a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e sqlite3_mutex_en
296b0 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 ter]([sqlite3_db
296c0 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f _mutex](D)) befo
296d0 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 re beginning.**
296e0 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 to use D and inv
296f0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d oking [sqlite3_m
29700 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c utex_leave]([sql
29710 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 ite3_db_mutex](D
29720 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 )) after.** all
29730 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 calls to the int
29740 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 erfaces listed h
29750 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 ere are complete
29760 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 d..**.** If an i
29770 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 nterface fails w
29780 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 ith SQLITE_MISUS
29790 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 E, that means th
297a0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 e interface.** w
297b0 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 as invoked incor
297c0 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 rectly by the ap
297d0 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 plication. In t
297e0 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a hat case, the.**
297f0 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 error code and
29800 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d message may or m
29810 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a ay not be set..*
29820 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 /.int sqlite3_er
29830 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 rcode(sqlite3 *d
29840 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f b);.int sqlite3_
29850 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 extended_errcode
29860 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 (sqlite3 *db);.c
29870 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
29880 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 e3_errmsg(sqlite
29890 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 3*);.const void
298a0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 *sqlite3_errmsg1
298b0 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 6(sqlite3*);.con
298c0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
298d0 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f _errstr(int);../
298e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 *.** CAPI3REF: P
298f0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
29900 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 t Object.** KEYW
29910 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 ORDS: {prepared
29920 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 statement} {prep
29930 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d ared statements}
29940 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e .**.** An instan
29950 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
29960 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 t represents a s
29970 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d ingle SQL statem
29980 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 ent that.** has
29990 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e been compiled in
299a0 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 to binary form a
299b0 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 nd is ready to b
299c0 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a e evaluated..**.
299d0 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 ** Think of each
299e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 SQL statement a
299f0 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d s a separate com
29a00 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 puter program.
29a10 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 The.** original
29a20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 SQL text is sour
29a30 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 ce code. A prep
29a40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f ared statement o
29a50 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 bject .** is the
29a60 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 compiled object
29a70 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 code. All SQL
29a80 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 must be converte
29a90 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 d into a.** prep
29aa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 ared statement b
29ab0 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 efore it can be
29ac0 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c run..**.** The l
29ad0 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 ife-cycle of a p
29ae0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
29af0 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 t object usually
29b00 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a goes like this:
29b10 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c .**.** <ol>.** <
29b20 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 li> Create the p
29b30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
29b40 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b t object using [
29b50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
29b60 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 v2()]..** <li> B
29b70 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 ind values to [p
29b80 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 arameters] using
29b90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
29ba0 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e d_*().** in
29bb0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 terfaces..** <li
29bc0 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 > Run the SQL by
29bd0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
29be0 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 3_step()] one or
29bf0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 more times..**
29c00 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 <li> Reset the p
29c10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
29c20 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
29c30 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 _reset()] then g
29c40 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 o back.** t
29c50 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 o step 2. Do th
29c60 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 is zero or more
29c70 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 times..** <li> D
29c80 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 estroy the objec
29c90 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
29ca0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a _finalize()]..**
29cb0 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 </ol>.*/.typede
29cc0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
29cd0 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 _stmt sqlite3_st
29ce0 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 mt;../*.** CAPI3
29cf0 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 REF: Run-time Li
29d00 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 mits.** METHOD:
29d10 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 sqlite3.**.** ^(
29d20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 This interface a
29d30 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f llows the size o
29d40 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 f various constr
29d50 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 ucts to be limit
29d60 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 ed.** on a conne
29d70 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 ction by connect
29d80 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 ion basis. The
29d90 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
29da0 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 is the.** [datab
29db0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
29dc0 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 whose limit is t
29dd0 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 o be set or quer
29de0 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 ied. The.** sec
29df0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
29e00 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d one of the [lim
29e10 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 it categories] t
29e20 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 hat define a.**
29e30 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 class of constru
29e40 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c cts to be size l
29e50 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 imited. The thi
29e60 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rd parameter is
29e70 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 the.** new limit
29e80 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 for that constr
29e90 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 uct.)^.**.** ^If
29ea0 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 the new limit i
29eb0 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d s a negative num
29ec0 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 ber, the limit i
29ed0 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 s unchanged..**
29ee0 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 ^(For each limit
29ef0 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 category SQLITE
29f00 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f _LIMIT_<i>NAME</
29f10 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a i> there is a .*
29f20 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 * [limits | hard
29f30 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a upper bound].**
29f40 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d set at compile-
29f50 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 time by a C prep
29f60 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 rocessor macro c
29f70 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 alled.** [limits
29f80 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 | SQLITE_MAX_<i
29f90 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 >NAME</i>]..** (
29fa0 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e The "_LIMIT_" in
29fb0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 the name is cha
29fc0 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e nged to "_MAX_".
29fd0 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 ))^.** ^Attempts
29fe0 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c to increase a l
29ff0 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 imit above its h
2a000 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 ard upper bound
2a010 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 are.** silently
2a020 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 truncated to the
2a030 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e hard upper boun
2a040 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 d..**.** ^Regard
2a050 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
2a060 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 or not the limit
2a070 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 was changed, th
2a080 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c e .** [sqlite3_l
2a090 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 imit()] interfac
2a0a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 e returns the pr
2a0b0 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 ior value of the
2a0c0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 limit..** ^Henc
2a0d0 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 e, to find the c
2a0e0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 urrent value of
2a0f0 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 a limit without
2a100 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 changing it,.**
2a110 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 simply invoke th
2a120 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 is interface wit
2a130 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 h the third para
2a140 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e meter set to -1.
2a150 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 .**.** Run-time
2a160 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e limits are inten
2a170 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 ded for use in a
2a180 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
2a190 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 manage.** both
2a1a0 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e their own intern
2a1b0 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 al database and
2a1c0 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 also databases t
2a1d0 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c hat are controll
2a1e0 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 ed.** by untrust
2a1f0 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 ed external sour
2a200 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 ces. An example
2a210 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 application mig
2a220 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 ht be a.** web b
2a230 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 rowser that has
2a240 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 its own database
2a250 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 s for storing hi
2a260 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 story and.** sep
2a270 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 arate databases
2a280 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 controlled by Ja
2a290 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 vaScript applica
2a2a0 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 tions downloaded
2a2b0 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 .** off the Inte
2a2c0 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 rnet. The inter
2a2d0 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 nal databases ca
2a2e0 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a n be given the.*
2a2f0 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 * large, default
2a300 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 limits. Databa
2a310 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 ses managed by e
2a320 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 xternal sources
2a330 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 can.** be given
2a340 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d much smaller lim
2a350 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 its designed to
2a360 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c prevent a denial
2a370 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 of service.** a
2a380 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 ttack. Develope
2a390 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 rs might also wa
2a3a0 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 nt to use the [s
2a3b0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
2a3c0 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 rizer()].** inte
2a3d0 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 rface to further
2a3e0 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 control untrust
2a3f0 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a ed SQL. The siz
2a400 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
2a410 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 e.** created by
2a420 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 an untrusted scr
2a430 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 ipt can be conta
2a440 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a ined using the.*
2a450 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e * [max_page_coun
2a460 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a t] [PRAGMA]..**.
2a470 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 ** New run-time
2a480 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 limit categories
2a490 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
2a4a0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
2a4b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2a4c0 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c _limit(sqlite3*,
2a4d0 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 int id, int new
2a4e0 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 Val);../*.** CAP
2a4f0 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 I3REF: Run-Time
2a500 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 Limit Categories
2a510 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c .** KEYWORDS: {l
2a520 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b imit category} {
2a530 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 *limit categorie
2a540 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 s}.**.** These c
2a550 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 onstants define
2a560 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 various performa
2a570 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 nce limits.** th
2a580 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 at can be lowere
2a590 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 d at run-time us
2a5a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d ing [sqlite3_lim
2a5b0 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 it()]..** The sy
2a5c0 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 nopsis of the me
2a5d0 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 anings of the va
2a5e0 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 rious limits is
2a5f0 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 shown below..**
2a600 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 Additional infor
2a610 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 mation is availa
2a620 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c ble at [limits |
2a630 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 Limits in SQLit
2a640 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a e]..**.** <dl>.*
2a650 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
2a660 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e _LENGTH]] ^(<dt>
2a670 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e SQLITE_LIMIT_LEN
2a680 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GTH</dt>.** <dd>
2a690 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 The maximum size
2a6a0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f of any string o
2a6b0 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 r BLOB or table
2a6c0 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 row, in bytes.<d
2a6d0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
2a6e0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 ITE_LIMIT_SQL_LE
2a6f0 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c NGTH]] ^(<dt>SQL
2a700 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 ITE_LIMIT_SQL_LE
2a710 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
2a720 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e >The maximum len
2a730 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 gth of an SQL st
2a740 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 atement, in byte
2a750 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 s.</dd>)^.**.**
2a760 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 [[SQLITE_LIMIT_C
2a770 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 OLUMN]] ^(<dt>SQ
2a780 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d LITE_LIMIT_COLUM
2a790 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 N</dt>.** <dd>Th
2a7a0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
2a7b0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 of columns in a
2a7c0 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f table definitio
2a7d0 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 n or in the.** r
2a7e0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b esult set of a [
2a7f0 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d SELECT] or the m
2a800 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
2a810 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 columns in an i
2a820 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e ndex.** or in an
2a830 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f ORDER BY or GRO
2a840 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 UP BY clause.</d
2a850 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
2a860 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 ITE_LIMIT_EXPR_D
2a870 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c EPTH]] ^(<dt>SQL
2a880 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 ITE_LIMIT_EXPR_D
2a890 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 EPTH</dt>.** <dd
2a8a0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 >The maximum dep
2a8b0 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 th of the parse
2a8c0 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 tree on any expr
2a8d0 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a ession.</dd>)^.*
2a8e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
2a8f0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c MIT_COMPOUND_SEL
2a900 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 ECT]] ^(<dt>SQLI
2a910 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
2a920 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a D_SELECT</dt>.**
2a930 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
2a940 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 number of terms
2a950 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 in a compound S
2a960 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e ELECT statement.
2a970 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
2a980 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 SQLITE_LIMIT_VDB
2a990 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c E_OP]] ^(<dt>SQL
2a9a0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f ITE_LIMIT_VDBE_O
2a9b0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 P</dt>.** <dd>Th
2a9c0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
2a9d0 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 of instructions
2a9e0 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 in a virtual ma
2a9f0 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a chine program.**
2aa00 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 used to impleme
2aa10 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d nt an SQL statem
2aa20 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 ent. If [sqlite
2aa30 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2aa40 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75 69 76 61 or.** the equiva
2aa50 6c 65 6e 74 20 74 72 69 65 73 20 74 6f 20 61 6c lent tries to al
2aa60 6c 6f 63 61 74 65 20 73 70 61 63 65 20 66 6f 72 locate space for
2aa70 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 69 73 20 more than this
2aa80 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 many opcodes.**
2aa90 69 6e 20 61 20 73 69 6e 67 6c 65 20 70 72 65 70 in a single prep
2aaa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 ared statement,
2aab0 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 an SQLITE_NOMEM
2aac0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 error is returne
2aad0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 d.</dd>)^.**.**
2aae0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 [[SQLITE_LIMIT_F
2aaf0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 UNCTION_ARG]] ^(
2ab00 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
2ab10 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 _FUNCTION_ARG</d
2ab20 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
2ab30 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
2ab40 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 arguments on a f
2ab50 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a unction.</dd>)^.
2ab60 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
2ab70 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 IMIT_ATTACHED]]
2ab80 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
2ab90 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e IT_ATTACHED</dt>
2aba0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
2abb0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 mum number of [A
2abc0 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 TTACH | attached
2abd0 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f databases].)^</
2abe0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
2abf0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 TE_LIMIT_LIKE_PA
2ac00 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a TTERN_LENGTH]].*
2ac10 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c * ^(<dt>SQLITE_L
2ac20 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 IMIT_LIKE_PATTER
2ac30 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a N_LENGTH</dt>.**
2ac40 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
2ac50 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 length of the p
2ac60 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 attern argument
2ac70 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 to the [LIKE] or
2ac80 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 .** [GLOB] opera
2ac90 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a tors.</dd>)^.**.
2aca0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
2acb0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
2acc0 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c R]].** ^(<dt>SQL
2acd0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
2ace0 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a LE_NUMBER</dt>.*
2acf0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
2ad00 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f m index number o
2ad10 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 f any [parameter
2ad20 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 ] in an SQL stat
2ad30 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b ement.)^.**.** [
2ad40 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 [SQLITE_LIMIT_TR
2ad50 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 IGGER_DEPTH]] ^(
2ad60 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
2ad70 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f _TRIGGER_DEPTH</
2ad80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
2ad90 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 aximum depth of
2ada0 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 recursion for tr
2adb0 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a iggers.</dd>)^.*
2adc0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
2add0 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 MIT_WORKER_THREA
2ade0 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 DS]] ^(<dt>SQLIT
2adf0 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 E_LIMIT_WORKER_T
2ae00 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c HREADS</dt>.** <
2ae10 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
2ae20 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 umber of auxilia
2ae30 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 ry worker thread
2ae40 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a s that a single.
2ae50 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
2ae60 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 tement] may star
2ae70 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 t.</dd>)^.** </d
2ae80 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
2ae90 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
2aea0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
2aeb0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 0.#define S
2aec0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f QLITE_LIMIT_SQL_
2aed0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 LENGTH
2aee0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
2aef0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c SQLITE_LIMIT_COL
2af00 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 UMN
2af10 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 2.#define
2af20 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 SQLITE_LIMIT_EX
2af30 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 PR_DEPTH
2af40 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 3.#defin
2af50 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 e SQLITE_LIMIT_C
2af60 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 OMPOUND_SELECT
2af70 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 4.#defi
2af80 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
2af90 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 VDBE_OP
2afa0 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 5.#def
2afb0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
2afc0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 _FUNCTION_ARG
2afd0 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 6.#de
2afe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
2aff0 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 T_ATTACHED
2b000 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 7.#d
2b010 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
2b020 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f IT_LIKE_PATTERN_
2b030 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 LENGTH 8.#
2b040 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
2b050 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
2b060 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a BER 9.
2b070 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
2b080 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 IMIT_TRIGGER_DEP
2b090 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 TH 10
2b0a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2b0b0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 LIMIT_WORKER_THR
2b0c0 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31 EADS 1
2b0d0 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 1../*.** CAPI3RE
2b0e0 46 3a 20 50 72 65 70 61 72 65 20 46 6c 61 67 73 F: Prepare Flags
2b0f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
2b100 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 stants define va
2b110 72 69 6f 75 73 20 66 6c 61 67 73 20 74 68 61 74 rious flags that
2b120 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 69 can be passed i
2b130 6e 74 6f 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67 nto.** "prepFlag
2b140 73 22 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 s" parameter of
2b150 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 the [sqlite3_pre
2b160 70 61 72 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a pare_v3()] and.*
2b170 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
2b180 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 74 65 72 re16_v3()] inter
2b190 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 faces..**.** New
2b1a0 20 66 6c 61 67 73 20 6d 61 79 20 62 65 20 61 64 flags may be ad
2b1b0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
2b1c0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
2b1d0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ..**.** <dl>.**
2b1e0 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 [[SQLITE_PREPARE
2b1f0 5f 50 45 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28 _PERSISTENT]] ^(
2b200 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 <dt>SQLITE_PREPA
2b210 52 45 5f 50 45 52 53 49 53 54 45 4e 54 3c 2f 64 RE_PERSISTENT</d
2b220 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 t>.** <dd>The SQ
2b230 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 LITE_PREPARE_PER
2b240 53 49 53 54 45 4e 54 20 66 6c 61 67 20 69 73 20 SISTENT flag is
2b250 61 20 68 69 6e 74 20 74 6f 20 74 68 65 20 71 75 a hint to the qu
2b260 65 72 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 ery planner.** t
2b270 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 hat the prepared
2b280 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 statement will
2b290 62 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 be retained for
2b2a0 61 20 6c 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a a long time and.
2b2b0 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 75 73 ** probably reus
2b2c0 65 64 20 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e ed many times.)^
2b2d0 20 5e 57 69 74 68 6f 75 74 20 74 68 69 73 20 66 ^Without this f
2b2e0 6c 61 67 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 lag, [sqlite3_pr
2b2f0 65 70 61 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 epare_v3()].** a
2b300 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
2b310 61 72 65 31 36 5f 76 33 28 29 5d 20 61 73 73 75 are16_v3()] assu
2b320 6d 65 20 74 68 61 74 20 74 68 65 20 70 72 65 70 me that the prep
2b330 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77 ared statement w
2b340 69 6c 6c 20 0a 2a 2a 20 62 65 20 75 73 65 64 20 ill .** be used
2b350 6a 75 73 74 20 6f 6e 63 65 20 6f 72 20 61 74 20 just once or at
2b360 6d 6f 73 74 20 61 20 66 65 77 20 74 69 6d 65 73 most a few times
2b370 20 61 6e 64 20 74 68 65 6e 20 64 65 73 74 72 6f and then destro
2b380 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 yed using.** [sq
2b390 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
2b3a0 5d 20 72 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f ] relatively soo
2b3b0 6e 2e 20 54 68 65 20 63 75 72 72 65 6e 74 20 69 n. The current i
2b3c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63 mplementation ac
2b3d0 74 73 0a 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69 ts.** on this hi
2b3e0 6e 74 20 62 79 20 61 76 6f 69 64 69 6e 67 20 74 nt by avoiding t
2b3f0 68 65 20 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 he use of [looka
2b400 73 69 64 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 side memory] so
2b410 61 73 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 as not to.** dep
2b420 6c 65 74 65 20 74 68 65 20 6c 69 6d 69 74 65 64 lete the limited
2b430 20 73 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 store of lookas
2b440 69 64 65 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75 ide memory. Futu
2b450 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a re versions of.*
2b460 2a 20 53 51 4c 69 74 65 20 6d 61 79 20 61 63 74 * SQLite may act
2b470 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 64 69 on this hint di
2b480 66 66 65 72 65 6e 74 6c 79 2e 0a 2a 2a 20 3c 2f fferently..** </
2b490 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
2b4a0 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 QLITE_PREPARE_PE
2b4b0 52 53 49 53 54 45 4e 54 20 20 20 20 20 20 20 20 RSISTENT
2b4c0 20 20 20 20 20 20 30 78 30 31 0a 0a 2f 2a 0a 2a 0x01../*.*
2b4d0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 * CAPI3REF: Comp
2b4e0 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 iling An SQL Sta
2b4f0 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 tement.** KEYWOR
2b500 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 DS: {SQL stateme
2b510 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 nt compiler}.**
2b520 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
2b530 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 ** CONSTRUCTOR:
2b540 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
2b550 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e ** To execute an
2b560 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
2b570 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 it must first be
2b580 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 compiled into a
2b590 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 byte-code.** pr
2b5a0 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 ogram using one
2b5b0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
2b5c0 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65 72 s. Or, in other
2b5d0 20 77 6f 72 64 73 2c 20 74 68 65 73 65 20 72 6f words, these ro
2b5e0 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63 6f utines.** are co
2b5f0 6e 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20 74 nstructors for t
2b600 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2b610 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a tement] object..
2b620 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66 65 72 **.** The prefer
2b630 72 65 64 20 72 6f 75 74 69 6e 65 20 74 6f 20 75 red routine to u
2b640 73 65 20 69 73 20 5b 73 71 6c 69 74 65 33 5f 70 se is [sqlite3_p
2b650 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 20 20 54 repare_v2()]. T
2b660 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 he.** [sqlite3_p
2b670 72 65 70 61 72 65 28 29 5d 20 69 6e 74 65 72 66 repare()] interf
2b680 61 63 65 20 69 73 20 6c 65 67 61 63 79 20 61 6e ace is legacy an
2b690 64 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 d should be avoi
2b6a0 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ded..** [sqlite3
2b6b0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 68 _prepare_v3()] h
2b6c0 61 73 20 61 6e 20 65 78 74 72 61 20 22 70 72 65 as an extra "pre
2b6d0 70 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20 74 pFlags" option t
2b6e0 68 61 74 20 69 73 20 75 73 65 64 0a 2a 2a 20 66 hat is used.** f
2b6f0 6f 72 20 73 70 65 63 69 61 6c 20 70 75 72 70 6f or special purpo
2b700 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 ses..**.** The u
2b710 73 65 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20 se of the UTF-8
2b720 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 70 72 interfaces is pr
2b730 65 66 65 72 72 65 64 2c 20 61 73 20 53 51 4c 69 eferred, as SQLi
2b740 74 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 te currently.**
2b750 64 6f 65 73 20 61 6c 6c 20 70 61 72 73 69 6e 67 does all parsing
2b760 20 75 73 69 6e 67 20 55 54 46 2d 38 2e 20 20 54 using UTF-8. T
2b770 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66 he UTF-16 interf
2b780 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 aces are provide
2b790 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65 6e d.** as a conven
2b7a0 69 65 6e 63 65 2e 20 20 54 68 65 20 55 54 46 2d ience. The UTF-
2b7b0 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 16 interfaces wo
2b7c0 72 6b 20 62 79 20 63 6f 6e 76 65 72 74 69 6e 67 rk by converting
2b7d0 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74 65 the.** input te
2b7e0 78 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20 74 xt into UTF-8, t
2b7f0 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 hen invoking the
2b800 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 55 corresponding U
2b810 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 2e 0a TF-8 interface..
2b820 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
2b830 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 argument, "db",
2b840 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 is a [database c
2b850 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 onnection] obtai
2b860 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 ned from a.** pr
2b870 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 ior successful c
2b880 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2b890 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
2b8a0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 3_open_v2()] or.
2b8b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ** [sqlite3_open
2b8c0 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 16()]. The data
2b8d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2b8e0 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 must not have be
2b8f0 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a en closed..**.**
2b900 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
2b910 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 ment, "zSql", is
2b920 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 the statement t
2b930 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 o be compiled, e
2b940 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 ncoded.** as eit
2b950 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 her UTF-8 or UTF
2b960 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 -16. The sqlite
2b970 33 5f 70 72 65 70 61 72 65 28 29 2c 20 73 71 6c 3_prepare(), sql
2b980 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2b990 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 ),.** and sqlite
2b9a0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 0a 2a 3_prepare_v3().*
2b9b0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 * interfaces use
2b9c0 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 UTF-8, and sqli
2b9d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 2c te3_prepare16(),
2b9e0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
2b9f0 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 16_v2(),.** and
2ba00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2ba10 36 5f 76 33 28 29 20 75 73 65 20 55 54 46 2d 31 6_v3() use UTF-1
2ba20 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 6..**.** ^If the
2ba30 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 nByte argument
2ba40 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
2ba50 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 n zSql is read u
2ba60 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 p to the.** firs
2ba70 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f t zero terminato
2ba80 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 r. ^If nByte is
2ba90 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 positive, then i
2baa0 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 t is the.** numb
2bab0 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 er of bytes read
2bac0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 from zSql. ^If
2bad0 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 nByte is zero,
2bae0 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 then no prepared
2baf0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 .** statement is
2bb00 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 generated..** I
2bb10 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f f the caller kno
2bb20 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70 ws that the supp
2bb30 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e lied string is n
2bb40 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 ul-terminated, t
2bb50 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 hen.** there is
2bb60 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 a small performa
2bb70 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f nce advantage to
2bb80 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 passing an nByt
2bb90 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 e parameter that
2bba0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 .** is the numbe
2bbb0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
2bbc0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c e input string <
2bbd0 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a i>including</i>.
2bbe0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 ** the nul-termi
2bbf0 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 nator..**.** ^If
2bc00 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e pzTail is not N
2bc10 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c ULL then *pzTail
2bc20 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e is made to poin
2bc30 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 t to the first b
2bc40 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 yte.** past the
2bc50 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 end of the first
2bc60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 SQL statement i
2bc70 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 n zSql. These r
2bc80 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 outines only.**
2bc90 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 compile the firs
2bca0 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a t statement in z
2bcb0 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 Sql, so *pzTail
2bcc0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 is left pointing
2bcd0 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 to.** what rema
2bce0 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a ins uncompiled..
2bcf0 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 **.** ^*ppStmt i
2bd00 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 s left pointing
2bd10 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 to a compiled [p
2bd20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2bd30 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a t] that can be.*
2bd40 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 * executed using
2bd50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2bd60 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 ]. ^If there is
2bd70 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 an error, *ppSt
2bd80 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 mt is set.** to
2bd90 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 NULL. ^If the i
2bda0 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 nput text contai
2bdb0 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 ns no SQL (if th
2bdc0 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d e input is an em
2bdd0 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 pty.** string or
2bde0 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e a comment) then
2bdf0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 *ppStmt is set
2be00 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 to NULL..** The
2be10 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 calling procedur
2be20 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 e is responsible
2be30 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 for deleting th
2be40 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 e compiled.** SQ
2be50 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e L statement usin
2be60 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
2be70 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 ize()] after it
2be80 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 has finished wit
2be90 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 h it..** ppStmt
2bea0 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e may not be NULL.
2beb0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 .**.** ^On succe
2bec0 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f ss, the sqlite3_
2bed0 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 prepare() family
2bee0 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 of routines ret
2bef0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b urn [SQLITE_OK];
2bf00 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e .** otherwise an
2bf10 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
2bf20 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
2bf30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 The sqlite3_pre
2bf40 70 61 72 65 5f 76 32 28 29 2c 20 73 71 6c 69 74 pare_v2(), sqlit
2bf50 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 2c e3_prepare_v3(),
2bf60 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
2bf70 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 16_v2(),.** and
2bf80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2bf90 36 5f 76 33 28 29 20 69 6e 74 65 72 66 61 63 65 6_v3() interface
2bfa0 73 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64 65 s are recommende
2bfb0 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 d for all new pr
2bfc0 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20 6f ograms..** The o
2bfd0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 lder interfaces
2bfe0 28 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 (sqlite3_prepare
2bff0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 () and sqlite3_p
2c000 72 65 70 61 72 65 31 36 28 29 29 0a 2a 2a 20 61 repare16()).** a
2c010 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 re retained for
2c020 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
2c030 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 ibility, but the
2c040 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 ir use is discou
2c050 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 raged..** ^In th
2c060 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 e "vX" interface
2c070 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 s, the prepared
2c080 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 statement.** tha
2c090 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 t is returned (t
2c0a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
2c0b0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 ] object) contai
2c0c0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 ns a copy of the
2c0d0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c .** original SQL
2c0e0 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 text. This caus
2c0f0 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f es the [sqlite3_
2c100 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 step()] interfac
2c110 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 e to.** behave d
2c120 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 ifferently in th
2c130 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 ree ways:.**.**
2c140 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 <ol>.** <li>.**
2c150 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 ^If the database
2c160 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c schema changes,
2c170 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 instead of retu
2c180 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 rning [SQLITE_SC
2c190 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 HEMA] as it.** a
2c1a0 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f lways used to do
2c1b0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
2c1c0 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 )] will automati
2c1d0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 cally recompile
2c1e0 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 the SQL.** state
2c1f0 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 ment and try to
2c200 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 run it again. As
2c210 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 many as [SQLITE
2c220 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 _MAX_SCHEMA_RETR
2c230 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 Y].** retries wi
2c240 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 ll occur before
2c250 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 sqlite3_step() g
2c260 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 ives up and retu
2c270 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a rns an error..**
2c280 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 </li>.**.** <li
2c290 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 >.** ^When an er
2c2a0 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c ror occurs, [sql
2c2b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c ite3_step()] wil
2c2c0 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 l return one of
2c2d0 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 the detailed.**
2c2e0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 [error codes] or
2c2f0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 [extended error
2c300 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c codes]. ^The l
2c310 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 egacy behavior w
2c320 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 as that.** [sqli
2c330 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c te3_step()] woul
2c340 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 d only return a
2c350 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f generic [SQLITE_
2c360 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f ERROR] result co
2c370 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 de.** and the ap
2c380 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 plication would
2c390 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 have to make a s
2c3a0 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 econd call to [s
2c3b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a qlite3_reset()].
2c3c0 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 ** in order to f
2c3d0 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 ind the underlyi
2c3e0 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 ng cause of the
2c3f0 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 problem. With th
2c400 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a e "v2" prepare.*
2c410 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 * interfaces, th
2c420 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 e underlying rea
2c430 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f son for the erro
2c440 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d r is returned im
2c450 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f mediately..** </
2c460 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a li>.**.** <li>.*
2c470 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 * ^If the specif
2c480 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 ic value bound t
2c490 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 o [parameter | h
2c4a0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 ost parameter] i
2c4b0 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 n the .** WHERE
2c4c0 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 clause might inf
2c4d0 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 luence the choic
2c4e0 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 e of query plan
2c4f0 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c for a statement,
2c500 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 .** then the sta
2c510 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 tement will be a
2c520 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 utomatically rec
2c530 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 ompiled, as if t
2c540 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a here had been .*
2c550 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 * a schema chang
2c560 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 e, on the first
2c570 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2c580 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 ] call following
2c590 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 any change.** t
2c5a0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 o the [sqlite3_b
2c5b0 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 ind_text | bindi
2c5c0 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 ngs] of that [pa
2c5d0 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 rameter]. .** ^T
2c5e0 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 he specific valu
2c5f0 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 e of WHERE-claus
2c600 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 e [parameter] mi
2c610 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 ght influence th
2c620 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 e .** choice of
2c630 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 query plan if th
2c640 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 e parameter is t
2c650 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 he left-hand sid
2c660 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a e of a [LIKE].**
2c670 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 or [GLOB] opera
2c680 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 tor or if the pa
2c690 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 rameter is compa
2c6a0 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 red to an indexe
2c6b0 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 d column.** and
2c6c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 the [SQLITE_ENAB
2c6d0 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c LE_STAT3] compil
2c6e0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 e-time option is
2c6f0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c enabled..** </l
2c700 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a i>.** </ol>.**.*
2c710 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72 * <p>^sqlite3_pr
2c720 65 70 61 72 65 5f 76 33 28 29 20 64 69 66 66 65 epare_v3() diffe
2c730 72 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f rs from sqlite3_
2c740 70 72 65 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c prepare_v2() onl
2c750 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74 y in having.** t
2c760 68 65 20 65 78 74 72 61 20 70 72 65 70 46 6c 61 he extra prepFla
2c770 67 73 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 gs parameter, wh
2c780 69 63 68 20 69 73 20 61 20 62 69 74 20 61 72 72 ich is a bit arr
2c790 61 79 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 ay consisting of
2c7a0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 zero or.** more
2c7b0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f of the [SQLITE_
2c7c0 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 PREPARE_PERSISTE
2c7d0 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45 50 41 52 NT|SQLITE_PREPAR
2c7e0 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68 E_*] flags. ^Th
2c7f0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 e.** sqlite3_pre
2c800 70 61 72 65 5f 76 32 28 29 20 69 6e 74 65 72 66 pare_v2() interf
2c810 61 63 65 20 77 6f 72 6b 73 20 65 78 61 63 74 6c ace works exactl
2c820 79 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a y the same as.**
2c830 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
2c840 5f 76 33 28 29 20 77 69 74 68 20 61 20 7a 65 72 _v3() with a zer
2c850 6f 20 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 o prepFlags para
2c860 6d 65 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 meter..*/.int sq
2c870 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 lite3_prepare(.
2c880 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
2c890 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
2c8a0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
2c8b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
2c8c0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
2c8d0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 statement, UTF-8
2c8e0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
2c8f0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
2c900 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
2c910 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
2c920 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
2c930 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
2c940 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
2c950 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
2c960 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
2c970 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
2c980 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
2c990 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
2c9a0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 f zSql */.);.int
2c9b0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
2c9c0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
2c9d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
2c9e0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
2c9f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
2ca00 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
2ca10 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
2ca20 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
2ca30 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
2ca40 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
2ca50 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
2ca60 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
2ca70 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
2ca80 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
2ca90 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
2caa0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
2cab0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
2cac0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
2cad0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
2cae0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
2caf0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
2cb00 72 65 70 61 72 65 5f 76 33 28 0a 20 20 73 71 6c repare_v3(. sql
2cb10 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
2cb20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
2cb30 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
2cb40 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
2cb50 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
2cb60 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 ement, UTF-8 enc
2cb70 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
2cb80 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
2cb90 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
2cba0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
2cbb0 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 ytes. */. unsig
2cbc0 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67 ned int prepFlag
2cbd0 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f s, /* Zero or mo
2cbe0 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 re SQLITE_PREPAR
2cbf0 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 E_ flags */. sq
2cc00 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
2cc10 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
2cc20 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
2cc30 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
2cc40 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
2cc50 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
2cc60 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
2cc70 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 zSql */.);.int
2cc80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2cc90 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 6(. sqlite3 *db
2cca0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
2ccb0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
2ccc0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
2ccd0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
2cce0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
2ccf0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
2cd00 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
2cd10 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
2cd20 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
2cd30 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
2cd40 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
2cd50 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
2cd60 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
2cd70 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
2cd80 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
2cd90 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
2cda0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
2cdb0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
2cdc0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 ;.int sqlite3_pr
2cdd0 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 epare16_v2(. sq
2cde0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
2cdf0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
2ce00 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
2ce10 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 nst void *zSql,
2ce20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
2ce30 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 tement, UTF-16 e
2ce40 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
2ce50 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
2ce60 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
2ce70 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
2ce80 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
2ce90 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
2cea0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
2ceb0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
2cec0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a . const void **
2ced0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
2cee0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
2cef0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
2cf00 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 zSql */.);.int s
2cf10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2cf20 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v3(. sqlite3 *
2cf30 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
2cf40 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
2cf50 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
2cf60 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f d *zSql, /
2cf70 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
2cf80 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 UTF-16 encoded
2cf90 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 */. int nByte,
2cfa0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
2cfb0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f Maximum length o
2cfc0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e f zSql in bytes.
2cfd0 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 */. unsigned i
2cfe0 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a nt prepFlags, /*
2cff0 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 Zero or more SQ
2d000 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c LITE_PREPARE_ fl
2d010 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 ags */. sqlite3
2d020 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
2d030 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
2d040 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
2d050 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 onst void **pzTa
2d060 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
2d070 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
2d080 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
2d090 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
2d0a0 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 PI3REF: Retrievi
2d0b0 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c ng Statement SQL
2d0c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
2d0d0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
2d0e0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 The sqlite3_sql(
2d0f0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 P) interface ret
2d100 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
2d110 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 o a copy of the
2d120 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 UTF-8.** SQL tex
2d130 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 t used to create
2d140 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2d150 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73 ment] P if P was
2d160 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 5b .** created by [
2d170 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2d180 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f v2()], [sqlite3_
2d190 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a 2a prepare_v3()],.*
2d1a0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
2d1b0 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b re16_v2()], or [
2d1c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2d1d0 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 6_v3()]..** ^The
2d1e0 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 sqlite3_expande
2d1f0 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 d_sql(P) interfa
2d200 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
2d210 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a nter to a UTF-8.
2d220 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 ** string contai
2d230 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78 ning the SQL tex
2d240 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73 74 t of prepared st
2d250 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a atement P with.*
2d260 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 * [bound paramet
2d270 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a ers] expanded..*
2d280 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 *.** ^(For examp
2d290 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72 65 le, if a prepare
2d2a0 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 d statement is c
2d2b0 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 reated using the
2d2c0 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 SQL.** text "SE
2d2d0 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 LECT $abc,:xyz"
2d2e0 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65 72 and if parameter
2d2f0 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74 $abc is bound t
2d300 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a o integer 2345.*
2d310 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 * and parameter
2d320 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c :xyz is unbound,
2d330 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 then sqlite3_sq
2d340 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a l() will return.
2d350 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 ** the original
2d360 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 string, "SELECT
2d370 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 $abc,:xyz" but s
2d380 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f qlite3_expanded_
2d390 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 sql().** will re
2d3a0 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34 turn "SELECT 234
2d3b0 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 5,NULL".)^.**.**
2d3c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
2d3d0 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 panded_sql() int
2d3e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e erface returns N
2d3f0 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 ULL if insuffici
2d400 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 ent memory.** is
2d410 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f available to ho
2d420 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f ld the result, o
2d430 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74 20 r if the result
2d440 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 would exceed the
2d450 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 .** the maximum
2d460 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 string length de
2d470 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 termined by the
2d480 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 [SQLITE_LIMIT_LE
2d490 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 NGTH]..**.** ^Th
2d4a0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f e [SQLITE_TRACE_
2d4b0 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 SIZE_LIMIT] comp
2d4c0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
2d4d0 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 limits the size
2d4e0 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 of.** bound para
2d4f0 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 meter expansions
2d500 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f . ^The [SQLITE_
2d510 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 OMIT_TRACE] comp
2d520 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 ile-time.** opti
2d530 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74 65 on causes sqlite
2d540 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 3_expanded_sql()
2d550 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72 to always retur
2d560 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 n NULL..**.** ^T
2d570 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e he string return
2d580 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 ed by sqlite3_sq
2d590 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20 l(P) is managed
2d5a0 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73 by SQLite and is
2d5b0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
2d5c0 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 y freed when the
2d5d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2d5e0 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 ent is finalized
2d5f0 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 ..** ^The string
2d600 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
2d610 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 ite3_expanded_sq
2d620 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 l(P), on the oth
2d630 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f er hand,.** is o
2d640 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
2d650 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
2d660 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65 65 and must be free
2d670 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 by the applicat
2d680 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e ion.** by passin
2d690 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 g it to [sqlite3
2d6a0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e _free()]..*/.con
2d6b0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
2d6c0 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d _sql(sqlite3_stm
2d6d0 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20 t *pStmt);.char
2d6e0 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 *sqlite3_expande
2d6f0 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 d_sql(sqlite3_st
2d700 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
2d710 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 ** CAPI3REF: Det
2d720 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c ermine If An SQL
2d730 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 Statement Write
2d740 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a s The Database.*
2d750 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
2d760 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
2d770 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 e sqlite3_stmt_r
2d780 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 eadonly(X) inter
2d790 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 face returns tru
2d7a0 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a e (non-zero) if.
2d7b0 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 ** and only if t
2d7c0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2d7d0 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 tement] X makes
2d7e0 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 no direct change
2d7f0 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 s to.** the cont
2d800 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 ent of the datab
2d810 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 ase file..**.**
2d820 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 Note that [appli
2d830 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
2d840 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 QL functions] or
2d850 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 .** [virtual tab
2d860 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 les] might chang
2d870 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 e the database i
2d880 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 ndirectly as a s
2d890 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a ide effect. .**
2d8a0 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ^(For example,
2d8b0 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f if an applicatio
2d8c0 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 n defines a func
2d8d0 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 tion "eval()" th
2d8e0 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 at .** calls [sq
2d8f0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 lite3_exec()], t
2d900 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e hen the followin
2d910 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 g SQL statement
2d920 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 would.** change
2d930 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
2d940 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 e through side-e
2d950 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ffects:.**.** <b
2d960 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
2d970 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 ** SELECT eva
2d980 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 l('DELETE FROM t
2d990 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 1') FROM t2;.**
2d9a0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
2d9b0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 te>.**.** But be
2d9c0 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 cause the [SELEC
2d9d0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 T] statement doe
2d9e0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 s not change the
2d9f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a database file.*
2da00 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 * directly, sqli
2da10 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c te3_stmt_readonl
2da20 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 y() would still
2da30 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a return true.)^.*
2da40 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f *.** ^Transactio
2da50 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d n control statem
2da60 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 ents such as [BE
2da70 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 GIN], [COMMIT],
2da80 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b [ROLLBACK],.** [
2da90 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 SAVEPOINT], and
2daa0 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 [RELEASE] cause
2dab0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 sqlite3_stmt_rea
2dac0 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 donly() to retur
2dad0 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 n true,.** since
2dae0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 the statements
2daf0 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f themselves do no
2db00 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 t actually modif
2db10 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 y the database b
2db20 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 ut.** rather the
2db30 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 y control the ti
2db40 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 ming of when oth
2db50 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f er statements mo
2db60 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 dify the .** dat
2db70 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 abase. ^The [AT
2db80 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 TACH] and [DETAC
2db90 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c H] statements al
2dba0 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 so cause.** sqli
2dbb0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c te3_stmt_readonl
2dbc0 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 y() to return tr
2dbd0 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 ue since, while
2dbe0 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 those statements
2dbf0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 .** change the c
2dc00 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 onfiguration of
2dc10 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 a database conne
2dc20 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e ction, they do n
2dc30 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e ot make .** chan
2dc40 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 ges to the conte
2dc50 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 nt of the databa
2dc60 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b se files on disk
2dc70 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
2dc80 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
2dc90 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
2dca0 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45 rns true for [BE
2dcb0 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 GIN] since.** [B
2dcc0 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74 EGIN] merely set
2dcd0 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73 s internal flags
2dce0 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e , but the [BEGIN
2dcf0 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45 |BEGIN IMMEDIATE
2dd00 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c ] and.** [BEGIN|
2dd10 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d BEGIN EXCLUSIVE]
2dd20 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75 commands do tou
2dd30 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ch the database
2dd40 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 and so.** sqlite
2dd50 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
2dd60 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 ) returns false
2dd70 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e for those comman
2dd80 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ds..*/.int sqlit
2dd90 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
2dda0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
2ddb0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
2ddc0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e PI3REF: Determin
2ddd0 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 e If A Prepared
2dde0 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 Statement Has Be
2ddf0 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 en Reset.** METH
2de00 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2de10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2de20 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 te3_stmt_busy(S)
2de30 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2de40 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 ns true (non-zer
2de50 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 o) if the.** [pr
2de60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2de70 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 ] S has been ste
2de80 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e pped at least on
2de90 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 ce using .** [sq
2dea0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 lite3_step(S)] b
2deb0 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 ut has neither r
2dec0 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e un to completion
2ded0 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 (returned.** [S
2dee0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d QLITE_DONE] from
2def0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
2df00 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 )]) nor.** been
2df10 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c reset using [sql
2df20 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 ite3_reset(S)].
2df30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 ^The sqlite3_st
2df40 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e mt_busy(S).** in
2df50 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2df60 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 false if S is a
2df70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 NULL pointer. I
2df80 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a f S is not a .**
2df90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e NULL pointer an
2dfa0 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 d is not a point
2dfb0 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 er to a valid [p
2dfc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2dfd0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 t].** object, th
2dfe0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
2dff0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 is undefined and
2e000 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 probably undesi
2e010 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 rable..**.** Thi
2e020 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 s interface can
2e030 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 be used in combi
2e040 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f nation [sqlite3_
2e050 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 next_stmt()].**
2e060 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 to locate all pr
2e070 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2e080 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 s associated wit
2e090 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a h a database .**
2e0a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
2e0b0 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 are in need of
2e0c0 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 being reset. Th
2e0d0 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a is can be used,.
2e0e0 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ** for example,
2e0f0 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f in diagnostic ro
2e100 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 utines to search
2e110 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a for prepared .*
2e120 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 * statements tha
2e130 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 t are holding a
2e140 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e transaction open
2e150 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2e160 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 _stmt_busy(sqlit
2e170 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
2e180 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 * CAPI3REF: Dyna
2e190 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 mically Typed Va
2e1a0 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 lue Object.** KE
2e1b0 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 YWORDS: {protect
2e1c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
2e1d0 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 } {unprotected s
2e1e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a qlite3_value}.**
2e1f0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 .** SQLite uses
2e200 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 the sqlite3_valu
2e210 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 e object to repr
2e220 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 esent all values
2e230 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 .** that can be
2e240 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 stored in a data
2e250 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 base table. SQLi
2e260 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 te uses dynamic
2e270 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 typing.** for th
2e280 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 e values it stor
2e290 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f es. ^Values sto
2e2a0 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 red in sqlite3_v
2e2b0 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 alue objects.**
2e2c0 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c can be integers,
2e2d0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
2e2e0 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c values, strings,
2e2f0 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e BLOBs, or NULL.
2e300 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 .**.** An sqlite
2e310 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 3_value object m
2e320 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 ay be either "pr
2e330 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 otected" or "unp
2e340 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f rotected"..** So
2e350 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 me interfaces re
2e360 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 quire a protecte
2e370 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
2e380 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 Other interfac
2e390 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 es.** will accep
2e3a0 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 t either a prote
2e3b0 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f cted or an unpro
2e3c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2e3d0 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 alue..** Every i
2e3e0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 nterface that ac
2e3f0 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 cepts sqlite3_va
2e400 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 lue arguments sp
2e410 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 ecifies.** wheth
2e420 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 er or not it req
2e430 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 uires a protecte
2e440 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
2e450 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 The.** [sqlite
2e460 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 3_value_dup()] i
2e470 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 nterface can be
2e480 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 used to construc
2e490 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 t a new .** prot
2e4a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2e4b0 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 lue from an unpr
2e4c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2e4d0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 value..**.** The
2e4e0 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 terms "protecte
2e4f0 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 d" and "unprotec
2e500 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 ted" refer to wh
2e510 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 ether or not.**
2e520 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e a mutex is held.
2e530 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 An internal mu
2e540 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 tex is held for
2e550 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 a protected.** s
2e560 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
2e570 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 ect but no mutex
2e580 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 is held for an
2e590 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
2e5a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
2e5b0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 ect. If SQLite
2e5c0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 is compiled to b
2e5d0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 e single-threade
2e5e0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 d.** (with [SQLI
2e5f0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
2e600 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 and with [sqlit
2e610 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d e3_threadsafe()]
2e620 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a returning 0).**
2e630 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 or if SQLite is
2e640 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 run in one of r
2e650 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 educed mutex mod
2e660 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 es .** [SQLITE_C
2e670 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
2e680 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 AD] or [SQLITE_C
2e690 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
2e6a0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 D].** then there
2e6b0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 is no distincti
2e6c0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 on between prote
2e6d0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 cted and unprote
2e6e0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
2e6f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e value objects an
2e700 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 d they can be us
2e710 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 ed interchangeab
2e720 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a ly. However,.**
2e730 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 for maximum cod
2e740 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 e portability it
2e750 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
2e760 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e that application
2e770 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 s.** still make
2e780 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 the distinction
2e790 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 between protecte
2e7a0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 d and unprotecte
2e7b0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
2e7c0 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 ue objects even
2e7d0 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c when not strictl
2e7e0 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a y required..**.*
2e7f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 * ^The sqlite3_v
2e800 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 alue objects tha
2e810 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 t are passed as
2e820 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 parameters into
2e830 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
2e840 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 ation of [applic
2e850 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
2e860 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 L functions] are
2e870 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e protected..** ^
2e880 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
2e890 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 e object returne
2e8a0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d by.** [sqlite3
2e8b0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
2e8c0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e is unprotected.
2e8d0 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 .** Unprotected
2e8e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2e8f0 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 jects may only b
2e900 65 20 75 73 65 64 20 61 73 20 61 72 67 75 6d 65 e used as argume
2e910 6e 74 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 nts.** to [sqlit
2e920 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
2e930 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e )], [sqlite3_bin
2e940 64 5f 76 61 6c 75 65 28 29 5d 2c 20 61 6e 64 0a d_value()], and.
2e950 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ** [sqlite3_valu
2e960 65 5f 64 75 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 e_dup()]..** The
2e970 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2e980 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 blob | sqlite3_v
2e990 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d alue_type()] fam
2e9a0 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 ily of.** interf
2e9b0 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f aces require pro
2e9c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2e9d0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f alue objects..*/
2e9e0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
2e9f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71 sqlite3_value sq
2ea00 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a lite3_value;../*
2ea10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 .** CAPI3REF: SQ
2ea20 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 L Function Conte
2ea30 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 xt Object.**.**
2ea40 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 The context in w
2ea50 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 hich an SQL func
2ea60 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 tion executes is
2ea70 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a stored in an.**
2ea80 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
2ea90 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 object. ^A poi
2eaa0 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 nter to an sqlit
2eab0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 e3_context objec
2eac0 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 t.** is always f
2ead0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
2eae0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 o [application-d
2eaf0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
2eb00 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 ions]..** The ap
2eb10 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2eb20 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 d SQL function i
2eb30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
2eb40 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 ll pass this.**
2eb50 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 pointer through
2eb60 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 into calls to [s
2eb70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
2eb80 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 t | sqlite3_resu
2eb90 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 lt()],.** [sqlit
2eba0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
2ebb0 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 text()], [sqlite
2ebc0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 3_user_data()],.
2ebd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ** [sqlite3_cont
2ebe0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d ext_db_handle()]
2ebf0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 , [sqlite3_get_a
2ec00 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e uxdata()],.** an
2ec10 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 d/or [sqlite3_se
2ec20 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f t_auxdata()]..*/
2ec30 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
2ec40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
2ec50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b sqlite3_context;
2ec60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2ec70 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 : Binding Values
2ec80 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 To Prepared Sta
2ec90 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f tements.** KEYWO
2eca0 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d RDS: {host param
2ecb0 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 eter} {host para
2ecc0 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 meters} {host pa
2ecd0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a rameter name}.**
2ece0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 KEYWORDS: {SQL
2ecf0 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 parameter} {SQL
2ed00 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 parameters} {par
2ed10 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a ameter binding}.
2ed20 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
2ed30 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 e3_stmt.**.** ^(
2ed40 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 In the SQL state
2ed50 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 ment text input
2ed60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 to [sqlite3_prep
2ed70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 are_v2()] and it
2ed80 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c s variants,.** l
2ed90 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 iterals may be r
2eda0 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 eplaced by a [pa
2edb0 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 rameter] that ma
2edc0 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c tches one of fol
2edd0 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 lowing.** templa
2ede0 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a tes:.**.** <ul>.
2edf0 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c ** <li> ?.** <l
2ee00 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e i> ?NNN.** <li>
2ee10 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 :VVV.** <li>
2ee20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 @VVV.** <li> $V
2ee30 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a VV.** </ul>.**.*
2ee40 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 * In the templat
2ee50 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 es above, NNN re
2ee60 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 presents an inte
2ee70 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 ger literal,.**
2ee80 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e and VVV represen
2ee90 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 ts an alphanumer
2eea0 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e ic identifier.)^
2eeb0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 ^The values of
2eec0 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 these.** parame
2eed0 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 ters (also calle
2eee0 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 d "host paramete
2eef0 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c r names" or "SQL
2ef00 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a parameters").**
2ef10 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e can be set usin
2ef20 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 g the sqlite3_bi
2ef30 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
2ef40 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a defined here..**
2ef50 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
2ef60 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 rgument to the s
2ef70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
2ef80 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 routines is alwa
2ef90 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 ys.** a pointer
2efa0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
2efb0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 stmt] object ret
2efc0 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 urned from.** [s
2efd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2efe0 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 2()] or its vari
2eff0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ants..**.** ^The
2f000 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
2f010 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
2f020 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 the SQL paramet
2f030 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a er to be set..**
2f040 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 ^The leftmost S
2f050 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 QL parameter has
2f060 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 an index of 1.
2f070 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 ^When the same
2f080 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 named.** SQL par
2f090 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d ameter is used m
2f0a0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 ore than once, s
2f0b0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 econd and subseq
2f0c0 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e uent.** occurren
2f0d0 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d ces have the sam
2f0e0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 e index as the f
2f0f0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e irst occurrence.
2f100 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 .** ^The index f
2f110 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 or named paramet
2f120 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 ers can be looke
2f130 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a d up using the.*
2f140 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2f150 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
2f160 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 )] API if desire
2f170 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a d. ^The index.*
2f180 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 * for "?NNN" par
2f190 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 ameters is the v
2f1a0 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 alue of NNN..**
2f1b0 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d ^The NNN value m
2f1c0 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 ust be between 1
2f1d0 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 and the [sqlite
2f1e0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 3_limit()].** pa
2f1f0 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f rameter [SQLITE_
2f200 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
2f210 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 UMBER] (default
2f220 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a value: 999)..**.
2f230 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 ** ^The third ar
2f240 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 gument is the va
2f250 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 lue to bind to t
2f260 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a he parameter..**
2f270 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 ^If the third p
2f280 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
2f290 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 te3_bind_text()
2f2a0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f or sqlite3_bind_
2f2b0 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 text16().** or s
2f2c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2f2d0 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 () is a NULL poi
2f2e0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f nter then the fo
2f2f0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a urth parameter.*
2f300 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 * is ignored and
2f310 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 the end result
2f320 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 is the same as s
2f330 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c qlite3_bind_null
2f340 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 ()..**.** ^(In t
2f350 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 hose routines th
2f360 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 at have a fourth
2f370 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 argument, its v
2f380 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e alue is the.** n
2f390 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
2f3a0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e n the parameter.
2f3b0 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 To be clear: t
2f3c0 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a he value is the.
2f3d0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e ** number of <u>
2f3e0 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 bytes</u> in the
2f3f0 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 value, not the
2f400 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
2f410 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 ters.)^.** ^If t
2f420 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
2f430 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ter to sqlite3_b
2f440 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 ind_text() or sq
2f450 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
2f460 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 6().** is negati
2f470 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e ve, then the len
2f480 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e gth of the strin
2f490 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 g is.** the numb
2f4a0 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 er of bytes up t
2f4b0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f o the first zero
2f4c0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 terminator..**
2f4d0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
2f4e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
2f4f0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 e3_bind_blob() i
2f500 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e s negative, then
2f510 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 .** the behavior
2f520 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
2f530 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 * If a non-negat
2f540 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d ive fourth param
2f550 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 eter is provided
2f560 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
2f570 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 _text().** or sq
2f580 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
2f590 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 6() or sqlite3_b
2f5a0 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 ind_text64() the
2f5b0 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 n.** that parame
2f5c0 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 ter must be the
2f5d0 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 byte offset.** w
2f5e0 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 here the NUL ter
2f5f0 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 minator would oc
2f600 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 cur assuming the
2f610 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c string were NUL
2f620 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 .** terminated.
2f630 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 If any NUL char
2f640 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 acters occur at
2f650 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 byte offsets les
2f660 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 s than .** the v
2f670 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 alue of the four
2f680 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 th parameter the
2f690 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 n the resulting
2f6a0 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c string value wil
2f6b0 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 l.** contain emb
2f6c0 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 edded NULs. The
2f6d0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 result of expre
2f6e0 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 ssions involving
2f6f0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 strings.** with
2f700 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 embedded NULs i
2f710 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
2f720 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 ** ^The fifth ar
2f730 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c gument to the BL
2f740 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 OB and string bi
2f750 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 nding interfaces
2f760 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 .** is a destruc
2f770 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 tor used to disp
2f780 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 ose of the BLOB
2f790 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 or.** string aft
2f7a0 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 er SQLite has fi
2f7b0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 nished with it.
2f7c0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 ^The destructor
2f7d0 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f is called.** to
2f7e0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 dispose of the
2f7f0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 BLOB or string e
2f800 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 ven if the call
2f810 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c to bind API fail
2f820 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 s..** ^If the fi
2f830 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a fth argument is.
2f840 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 ** the special v
2f850 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 alue [SQLITE_STA
2f860 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 TIC], then SQLit
2f870 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 e assumes that t
2f880 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f he.** informatio
2f890 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 n is in static,
2f8a0 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 unmanaged space
2f8b0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 and does not nee
2f8c0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a d to be freed..*
2f8d0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 * ^If the fifth
2f8e0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 argument has the
2f8f0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 value [SQLITE_T
2f900 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a RANSIENT], then.
2f910 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ** SQLite makes
2f920 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
2f930 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 copy of the data
2f940 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 immediately, be
2f950 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 fore.** the sqli
2f960 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
2f970 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a tine returns..**
2f980 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 .** ^The sixth a
2f990 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
2f9a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 e3_bind_text64()
2f9b0 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a must be one of.
2f9c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d ** [SQLITE_UTF8]
2f9d0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d , [SQLITE_UTF16]
2f9e0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 , [SQLITE_UTF16B
2f9f0 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 E], or [SQLITE_U
2fa00 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 TF16LE].** to sp
2fa10 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 ecify the encodi
2fa20 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 ng of the text i
2fa30 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 n the third para
2fa40 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 meter. If.** th
2fa50 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 e sixth argument
2fa60 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
2fa70 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 _text64() is not
2fa80 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 one of the.** a
2fa90 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 llowed values sh
2faa0 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 own above, or if
2fab0 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 the text encodi
2fac0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a ng is different.
2fad0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f ** from the enco
2fae0 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 ding specified b
2faf0 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61 y the sixth para
2fb00 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 meter, then the
2fb10 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 behavior.** is u
2fb20 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
2fb30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e ^The sqlite3_bin
2fb40 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 d_zeroblob() rou
2fb50 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f tine binds a BLO
2fb60 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 B of length N th
2fb70 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 at.** is filled
2fb80 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 with zeroes. ^A
2fb90 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 zeroblob uses a
2fba0 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 fixed amount of
2fbb0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 memory.** (just
2fbc0 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 an integer to h
2fbd0 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 old its size) wh
2fbe0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 ile it is being
2fbf0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 processed..** Ze
2fc00 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 roblobs are inte
2fc10 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 nded to serve as
2fc20 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f placeholders fo
2fc30 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a r BLOBs whose.**
2fc40 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 content is late
2fc50 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a r written using.
2fc60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ** [sqlite3_blob
2fc70 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e _open | incremen
2fc80 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f tal BLOB I/O] ro
2fc90 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 utines..** ^A ne
2fca0 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 gative value for
2fcb0 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 the zeroblob re
2fcc0 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d sults in a zero-
2fcd0 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a length BLOB..**.
2fce0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2fcf0 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49 bind_pointer(S,I
2fd00 2c 50 2c 54 2c 44 29 20 72 6f 75 74 69 6e 65 20 ,P,T,D) routine
2fd10 63 61 75 73 65 73 20 74 68 65 20 49 2d 74 68 20 causes the I-th
2fd20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 parameter in.**
2fd30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2fd40 65 6e 74 5d 20 53 20 74 6f 20 68 61 76 65 20 61 ent] S to have a
2fd50 6e 20 53 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e n SQL value of N
2fd60 55 4c 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f ULL, but to also
2fd70 20 62 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 be.** associate
2fd80 64 20 77 69 74 68 20 74 68 65 20 70 6f 69 6e 74 d with the point
2fd90 65 72 20 50 20 6f 66 20 74 79 70 65 20 54 2e 20 er P of type T.
2fda0 20 5e 44 20 69 73 20 65 69 74 68 65 72 20 61 20 ^D is either a
2fdb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 0a NULL pointer or.
2fdc0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
2fdd0 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e a destructor fun
2fde0 63 74 69 6f 6e 20 66 6f 72 20 50 2e 20 5e 53 51 ction for P. ^SQ
2fdf0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 Lite will invoke
2fe00 20 74 68 65 0a 2a 2a 20 64 65 73 74 72 75 63 74 the.** destruct
2fe10 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 or D with a sing
2fe20 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 50 le argument of P
2fe30 20 77 68 65 6e 20 69 74 20 69 73 20 66 69 6e 69 when it is fini
2fe40 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 50 2e shed using.** P.
2fe50 20 20 54 68 65 20 54 20 70 61 72 61 6d 65 74 65 The T paramete
2fe60 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 73 74 r should be a st
2fe70 61 74 69 63 20 73 74 72 69 6e 67 2c 20 70 72 65 atic string, pre
2fe80 66 65 72 61 62 6c 79 20 61 20 73 74 72 69 6e 67 ferably a string
2fe90 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 20 54 68 65 .** literal. The
2fea0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f sqlite3_bind_po
2feb0 69 6e 74 65 72 28 29 20 72 6f 75 74 69 6e 65 20 inter() routine
2fec0 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a is part of the.*
2fed0 2a 20 5b 70 6f 69 6e 74 65 72 20 70 61 73 73 69 * [pointer passi
2fee0 6e 67 20 69 6e 74 65 72 66 61 63 65 5d 20 61 64 ng interface] ad
2fef0 64 65 64 20 66 6f 72 20 53 51 4c 69 74 65 20 33 ded for SQLite 3
2ff00 2e 32 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 .20.0..**.** ^If
2ff10 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 any of the sqli
2ff20 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
2ff30 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
2ff40 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 with a NULL poi
2ff50 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 nter.** for the
2ff60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2ff70 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 ent] or with a p
2ff80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2ff90 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b t for which.** [
2ffa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2ffb0 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 has been called
2ffc0 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 more recently th
2ffd0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 an [sqlite3_rese
2ffe0 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 t()],.** then th
2fff0 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 e call will retu
30000 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 rn [SQLITE_MISUS
30010 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 E]. If any sqli
30020 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 te3_bind_().** r
30030 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 outine is passed
30040 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
30050 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 tement] that has
30060 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c been finalized,
30070 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 the.** result i
30080 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
30090 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c probably harmful
300a0 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 ..**.** ^Binding
300b0 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 s are not cleare
300c0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
300d0 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 3_reset()] routi
300e0 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 ne..** ^Unbound
300f0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 parameters are i
30100 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 nterpreted as NU
30110 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 LL..**.** ^The s
30120 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f qlite3_bind_* ro
30130 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 utines return [S
30140 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
30150 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 cess or an.** [e
30160 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e rror code] if an
30170 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e ything goes wron
30180 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 g..** ^[SQLITE_T
30190 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 OOBIG] might be
301a0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 returned if the
301b0 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 size of a string
301c0 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 or BLOB.** exce
301d0 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 eds limits impos
301e0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c ed by [sqlite3_l
301f0 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 imit]([SQLITE_LI
30200 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a MIT_LENGTH]) or.
30210 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c ** [SQLITE_MAX_L
30220 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c ENGTH]..** ^[SQL
30230 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 ITE_RANGE] is re
30240 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 turned if the pa
30250 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 rameter.** index
30260 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
30270 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 . ^[SQLITE_NOME
30280 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 M] is returned i
30290 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 f malloc() fails
302a0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
302b0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
302c0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
302d0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
302e0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
302f0 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c ame()], and [sql
30300 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
30310 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
30320 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
30330 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 d_blob(sqlite3_s
30340 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
30350 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 void*, int n, v
30360 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
30370 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
30380 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f _blob64(sqlite3_
30390 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
303a0 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 t void*, sqlite3
303b0 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 _uint64,.
303c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
303d0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
303e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
303f0 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 nd_double(sqlite
30400 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 3_stmt*, int, do
30410 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 uble);.int sqlit
30420 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 e3_bind_int(sqli
30430 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
30440 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 int);.int sqlite
30450 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 3_bind_int64(sql
30460 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
30470 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b sqlite3_int64);
30480 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
30490 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 d_null(sqlite3_s
304a0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 tmt*, int);.int
304b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
304c0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
304d0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c int,const char*,
304e0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 int,void(*)(void
304f0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 *));.int sqlite3
30500 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c _bind_text16(sql
30510 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
30520 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
30530 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
30540 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f ));.int sqlite3_
30550 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 bind_text64(sqli
30560 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
30570 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c const char*, sql
30580 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 ite3_uint64,.
30590 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
305a0 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f void(*)(vo
305b0 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 id*), unsigned c
305c0 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 har encoding);.i
305d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
305e0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 value(sqlite3_st
305f0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
30600 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
30610 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
30620 64 5f 70 6f 69 6e 74 65 72 28 73 71 6c 69 74 65 d_pointer(sqlite
30630 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f 3_stmt*, int, vo
30640 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a id*, const char*
30650 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 ,void(*)(void*))
30660 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
30670 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 nd_zeroblob(sqli
30680 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
30690 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 int n);.int sqli
306a0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f te3_bind_zeroblo
306b0 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 b64(sqlite3_stmt
306c0 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f *, int, sqlite3_
306d0 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 uint64);../*.**
306e0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
306f0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 Of SQL Paramete
30700 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 rs.** METHOD: sq
30710 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
30720 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 ^This routine c
30730 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 an be used to fi
30740 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 nd the number of
30750 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 [SQL parameters
30760 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 ].** in a [prepa
30770 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 red statement].
30780 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 SQL parameters
30790 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 are tokens of th
307a0 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 e.** form "?", "
307b0 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 ?NNN", ":AAA", "
307c0 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 $AAA", or "@AAA"
307d0 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a that serve as.*
307e0 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 * placeholders f
307f0 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 or values that a
30800 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 re [sqlite3_bind
30810 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a _blob | bound].*
30820 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 * to the paramet
30830 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 ers at a later t
30840 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 ime..**.** ^(Thi
30850 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c s routine actual
30860 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 ly returns the i
30870 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 ndex of the larg
30880 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a est (rightmost).
30890 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f ** parameter. Fo
308a0 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 r all forms exce
308b0 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 pt ?NNN, this wi
308c0 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f ll correspond to
308d0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
308e0 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 f unique paramet
308f0 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 ers. If paramet
30900 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 ers of the ?NNN
30910 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a form are used,.*
30920 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 * there may be g
30930 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e aps in the list.
30940 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 )^.**.** See als
30950 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
30960 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
30970 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nd()],.** [sqlit
30980 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
30990 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a r_name()], and.*
309a0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
309b0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
309c0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 )]..*/.int sqlit
309d0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
309e0 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f r_count(sqlite3_
309f0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
30a00 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 API3REF: Name Of
30a10 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 A Host Paramete
30a20 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c r.** METHOD: sql
30a30 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
30a40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e ^The sqlite3_bin
30a50 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
30a60 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 (P,N) interface
30a70 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e returns.** the n
30a80 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 ame of the N-th
30a90 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 [SQL parameter]
30aa0 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 in the [prepared
30ab0 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a statement] P..*
30ac0 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 * ^(SQL paramete
30ad0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 rs of the form "
30ae0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 ?NNN" or ":AAA"
30af0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 or "@AAA" or "$A
30b00 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 AA".** have a na
30b10 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 me which is the
30b20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 string "?NNN" or
30b30 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 ":AAA" or "@AAA
30b40 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 " or "$AAA".** r
30b50 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
30b60 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
30b70 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 the initial ":"
30b80 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 or "$" or "@" or
30b90 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 "?".** is inclu
30ba0 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 ded as part of t
30bb0 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 he name.)^.** ^P
30bc0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
30bd0 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 form "?" withou
30be0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e t a following in
30bf0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 teger have no na
30c00 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 me.** and are re
30c10 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 ferred to as "na
30c20 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e meless" or "anon
30c30 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 ymous parameters
30c40 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 "..**.** ^The fi
30c50 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 rst host paramet
30c60 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 er has an index
30c70 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a of 1, not 0..**.
30c80 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 ** ^If the value
30c90 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e N is out of ran
30ca0 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 ge or if the N-t
30cb0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a h parameter is.*
30cc0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e * nameless, then
30cd0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 NULL is returne
30ce0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 d. ^The returne
30cf0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 d string is.** a
30d00 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 lways in UTF-8 e
30d10 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 ncoding even if
30d20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 the named parame
30d30 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 ter was.** origi
30d40 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 nally specified
30d50 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 as UTF-16 in [sq
30d60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
30d70 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
30d80 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c prepare16_v2()],
30d90 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
30da0 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a pare16_v3()]..**
30db0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
30dc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
30dd0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
30de0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
30df0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
30e00 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 nt()], and.** [s
30e10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
30e20 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
30e30 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
30e40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
30e50 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 meter_name(sqlit
30e60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a e3_stmt*, int);.
30e70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
30e80 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 Index Of A Para
30e90 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 meter With A Giv
30ea0 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f en Name.** METHO
30eb0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
30ec0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 **.** ^Return th
30ed0 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 e index of an SQ
30ee0 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 L parameter give
30ef0 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 n its name. ^Th
30f00 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 e.** index value
30f10 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 returned is sui
30f20 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 table for use as
30f30 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 the second.** p
30f40 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
30f50 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
30f60 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 qlite3_bind()].
30f70 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 ^A zero.** is r
30f80 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 eturned if no ma
30f90 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 tching parameter
30fa0 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 is found. ^The
30fb0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 parameter.** na
30fc0 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e me must be given
30fd0 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 in UTF-8 even i
30fe0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 f the original s
30ff0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 tatement.** was
31000 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 prepared from UT
31010 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 F-16 text using
31020 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
31030 31 36 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 16_v2()] or.** [
31040 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
31050 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 6_v3()]..**.** S
31060 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
31070 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
31080 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
31090 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
310a0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
310b0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
310c0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
310d0 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 _name()]..*/.int
310e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 sqlite3_bind_pa
310f0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 rameter_index(sq
31100 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e lite3_stmt*, con
31110 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b st char *zName);
31120 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
31130 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 : Reset All Bind
31140 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 ings On A Prepar
31150 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 ed Statement.**
31160 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
31170 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 stmt.**.** ^Cont
31180 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 rary to the intu
31190 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b ition of many, [
311a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
311b0 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a does not reset.
311c0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ** the [sqlite3_
311d0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 bind_blob | bind
311e0 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 ings] on a [prep
311f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
31200 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f .** ^Use this ro
31210 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 utine to reset a
31220 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 ll host paramete
31230 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 rs to NULL..*/.i
31240 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 nt sqlite3_clear
31250 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 _bindings(sqlite
31260 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
31270 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 CAPI3REF: Numbe
31280 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 r Of Columns In
31290 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 A Result Set.**
312a0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
312b0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 stmt.**.** ^Retu
312c0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 rn the number of
312d0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
312e0 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 result set retur
312f0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 ned by the.** [p
31300 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
31310 74 5d 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75 t]. ^If this rou
31320 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20 tine returns 0,
31330 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a that means the .
31340 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
31350 74 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 tement] returns
31360 6e 6f 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 no data (for exa
31370 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d mple an [UPDATE]
31380 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 )..** ^However,
31390 6a 75 73 74 20 62 65 63 61 75 73 65 20 74 68 69 just because thi
313a0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
313b0 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d s a positive num
313c0 62 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 ber does not.**
313d0 6d 65 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 mean that one or
313e0 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61 more rows of da
313f0 74 61 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 ta will be retur
31400 6e 65 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 ned. ^A SELECT
31410 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c statement.** wil
31420 6c 20 61 6c 77 61 79 73 20 68 61 76 65 20 61 20 l always have a
31430 70 6f 73 69 74 69 76 65 20 73 71 6c 69 74 65 33 positive sqlite3
31440 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 _column_count()
31450 62 75 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e but depending on
31460 20 74 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c the.** WHERE cl
31470 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 ause constraints
31480 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63 and the table c
31490 6f 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 ontent, it might
314a0 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e return no rows.
314b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
314c0 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 [sqlite3_data_c
314d0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 ount()].*/.int s
314e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f qlite3_column_co
314f0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
31500 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
31510 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d CAPI3REF: Colum
31520 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 n Names In A Res
31530 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f ult Set.** METHO
31540 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
31550 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
31560 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 tines return the
31570 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 name assigned t
31580 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 o a particular c
31590 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 olumn.** in the
315a0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 result set of a
315b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
315c0 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 nt. ^The sqlite
315d0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 3_column_name().
315e0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 ** interface ret
315f0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
31600 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 o a zero-termina
31610 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 ted UTF-8 string
31620 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f .** and sqlite3_
31630 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 column_name16()
31640 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
31650 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d r to a zero-term
31660 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 inated.** UTF-16
31670 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 string. ^The f
31680 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
31690 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 s the [prepared
316a0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 statement].** th
316b0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 at implements th
316c0 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 e [SELECT] state
316d0 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e ment. ^The secon
316e0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
316f0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d he.** column num
31700 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d ber. ^The leftm
31710 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 ost column is nu
31720 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 mber 0..**.** ^T
31730 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
31740 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 ng pointer is va
31750 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 lid until either
31760 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
31770 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 tatement].** is
31780 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 destroyed by [sq
31790 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
317a0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 ] or until the s
317b0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f tatement is auto
317c0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 matically.** rep
317d0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 repared by the f
317e0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 irst call to [sq
317f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f lite3_step()] fo
31800 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 r a particular r
31810 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 un.** or until t
31820 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a he next call to.
31830 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
31840 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 n_name() or sqli
31850 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
31860 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 6() on the same
31870 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 column..**.** ^I
31880 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 f sqlite3_malloc
31890 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 () fails during
318a0 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f the processing o
318b0 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 f either routine
318c0 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 .** (for example
318d0 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 during a conver
318e0 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 sion from UTF-8
318f0 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 to UTF-16) then
31900 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
31910 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a r is returned..*
31920 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f *.** ^The name o
31930 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d f a result colum
31940 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f n is the value o
31950 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 f the "AS" claus
31960 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f e for.** that co
31970 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 lumn, if there i
31980 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 s an AS clause.
31990 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 If there is no
319a0 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 AS clause.** the
319b0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
319c0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 e column is unsp
319d0 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 ecified and may
319e0 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f change from.** o
319f0 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 ne release of SQ
31a00 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 Lite to the next
31a10 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 ..*/.const char
31a20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
31a30 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
31a40 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 t*, int N);.cons
31a50 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
31a60 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 column_name16(sq
31a70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
31a80 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 N);../*.** CAPI
31a90 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 3REF: Source Of
31aa0 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 Data In A Query
31ab0 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 Result.** METHOD
31ac0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
31ad0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
31ae0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d ines provide a m
31af0 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e eans to determin
31b00 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 e the database,
31b10 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 table, and.** ta
31b20 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 ble column that
31b30 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 is the origin of
31b40 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 a particular re
31b50 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a sult column in.*
31b60 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 * [SELECT] state
31b70 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 ment..** ^The na
31b80 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
31b90 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 se or table or c
31ba0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 olumn can be ret
31bb0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 urned as.** eith
31bc0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 er a UTF-8 or UT
31bd0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 F-16 string. ^T
31be0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f he _database_ ro
31bf0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a utines return.**
31c00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 the database na
31c10 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 me, the _table_
31c20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
31c30 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 the table name,
31c40 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 and.** the origi
31c50 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 n_ routines retu
31c60 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 rn the column na
31c70 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 me..** ^The retu
31c80 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 rned string is v
31c90 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b alid until the [
31ca0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
31cb0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 nt] is destroyed
31cc0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 .** using [sqlit
31cd0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
31ce0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 r until the stat
31cf0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 ement is automat
31d00 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 ically.** reprep
31d10 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 ared by the firs
31d20 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
31d30 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 e3_step()] for a
31d40 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a particular run.
31d50 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 ** or until the
31d60 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e same information
31d70 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a is requested.**
31d80 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 again in a diff
31d90 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a erent encoding..
31da0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 **.** ^The names
31db0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 returned are th
31dc0 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c e original un-al
31dd0 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 iased names of t
31de0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 he.** database,
31df0 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d table, and colum
31e00 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 n..**.** ^The fi
31e10 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
31e20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
31e30 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 is a [prepared
31e40 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e statement]..** ^
31e50 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
31e60 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 return informati
31e70 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 on about the Nth
31e80 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 result column r
31e90 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 eturned by.** th
31ea0 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 e statement, whe
31eb0 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f re N is the seco
31ec0 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 nd function argu
31ed0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 ment..** ^The le
31ee0 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 ft-most column i
31ef0 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 s column 0 for t
31f00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a hese routines..*
31f10 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 *.** ^If the Nth
31f20 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 column returned
31f30 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e by the statemen
31f40 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 t is an expressi
31f50 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 on or.** subquer
31f60 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 y and is not a c
31f70 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 olumn value, the
31f80 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 n all of these f
31f90 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a unctions return.
31fa0 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 ** NULL. ^These
31fb0 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 routine might a
31fc0 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 lso return NULL
31fd0 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f if a memory allo
31fe0 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 cation error.**
31ff0 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 occurs. ^Otherw
32000 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e ise, they return
32010 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
32020 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 attached databa
32030 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 se, table,.** or
32040 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 column that que
32050 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e ry result column
32060 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 was extracted f
32070 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 rom..**.** ^As w
32080 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 ith all other SQ
32090 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 Lite APIs, those
320a0 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 whose names end
320b0 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 with "16" retur
320c0 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f n.** UTF-16 enco
320d0 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 ded strings and
320e0 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 the other functi
320f0 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 ons return UTF-8
32100 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 ..**.** ^These A
32110 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 PIs are only ava
32120 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 ilable if the li
32130 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c brary was compil
32140 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ed with the.** [
32150 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f SQLITE_ENABLE_CO
32160 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 LUMN_METADATA] C
32170 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 -preprocessor sy
32180 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 mbol..**.** If t
32190 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 wo or more threa
321a0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d ds call one or m
321b0 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 ore of these rou
321c0 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 tines against th
321d0 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 e same.** prepar
321e0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 ed statement and
321f0 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 column at the s
32200 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 ame time then th
32210 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a e results are.**
32220 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
32230 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 * If two or more
32240 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e threads call on
32250 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 e or more.** [sq
32260 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 lite3_column_dat
32270 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c abase_name | col
32280 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 umn metadata int
32290 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 erfaces].** for
322a0 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 the same [prepar
322b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e ed statement] an
322c0 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a d result column.
322d0 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 ** at the same t
322e0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 ime then the res
322f0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
32300 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 ed..*/.const cha
32310 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
32320 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 n_database_name(
32330 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
32340 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a t);.const void *
32350 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
32360 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 atabase_name16(s
32370 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
32380 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
32390 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 qlite3_column_ta
323a0 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ble_name(sqlite3
323b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
323c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
323d0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 _column_table_na
323e0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
323f0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 t*,int);.const c
32400 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
32410 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 umn_origin_name(
32420 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
32430 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a t);.const void *
32440 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f sqlite3_column_o
32450 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c rigin_name16(sql
32460 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
32470 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
32480 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 : Declared Datat
32490 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 ype Of A Query R
324a0 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a esult.** METHOD:
324b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
324c0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 .** ^(The first
324d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b parameter is a [
324e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
324f0 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 nt]..** If this
32500 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b statement is a [
32510 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
32520 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f t and the Nth co
32530 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 lumn of the.** r
32540 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 eturned result s
32550 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 et of that [SELE
32560 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 CT] is a table c
32570 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a olumn (not an.**
32580 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 expression or s
32590 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 ubquery) then th
325a0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 e declared type
325b0 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 of the table.**
325c0 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e column is return
325d0 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e ed.)^ ^If the N
325e0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 th column of the
325f0 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 result set is a
32600 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 n.** expression
32610 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 or subquery, the
32620 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 n a NULL pointer
32630 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
32640 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 ^The returned s
32650 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 tring is always
32660 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a UTF-8 encoded..*
32670 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 *.** ^(For examp
32680 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 le, given the da
32690 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a tabase schema:.*
326a0 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c *.** CREATE TABL
326b0 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 E t1(c1 VARIANT)
326c0 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 ;.**.** and the
326d0 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d following statem
326e0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c ent to be compil
326f0 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 ed:.**.** SELECT
32700 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d c1 + 1, c1 FROM
32710 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 t1;.**.** this
32720 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 routine would re
32730 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 turn the string
32740 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 "VARIANT" for th
32750 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a e second result.
32760 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 ** column (i==1)
32770 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 , and a NULL poi
32780 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 nter for the fir
32790 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e st result column
327a0 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a (i==0).)^.**.**
327b0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 ^SQLite uses dy
327c0 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 namic run-time t
327d0 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 yping. ^So just
327e0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d because a colum
327f0 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 n.** is declared
32800 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 to contain a pa
32810 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f rticular type do
32820 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 es not mean that
32830 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f the.** data sto
32840 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 red in that colu
32850 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 mn is of the dec
32860 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c lared type. SQL
32870 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 ite is.** strong
32880 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 ly typed, but th
32890 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 e typing is dyna
328a0 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 mic not static.
328b0 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 ^Type.** is ass
328c0 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 ociated with ind
328d0 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 ividual values,
328e0 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e not with the con
328f0 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 tainers.** used
32900 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 to hold those va
32910 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 lues..*/.const c
32920 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
32930 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c umn_decltype(sql
32940 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
32950 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
32960 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c ite3_column_decl
32970 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 type16(sqlite3_s
32980 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a tmt*,int);../*.*
32990 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c * CAPI3REF: Eval
329a0 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 uate An SQL Stat
329b0 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a ement.** METHOD:
329c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
329d0 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 .** After a [pre
329e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
329f0 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 has been prepar
32a00 65 64 20 75 73 69 6e 67 20 61 6e 79 20 6f 66 0a ed using any of.
32a10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
32a20 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
32a30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 te3_prepare_v3()
32a40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ], [sqlite3_prep
32a50 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 are16_v2()],.**
32a60 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
32a70 61 72 65 31 36 5f 76 33 28 29 5d 20 6f 72 20 6f are16_v3()] or o
32a80 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 ne of the legacy
32a90 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b .** interfaces [
32aa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
32ab0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
32ac0 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 repare16()], thi
32ad0 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 s function.** mu
32ae0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 st be called one
32af0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 or more times t
32b00 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 o evaluate the s
32b10 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 tatement..**.**
32b20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 The details of t
32b30 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 he behavior of t
32b40 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 he sqlite3_step(
32b50 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 ) interface depe
32b60 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 nd.** on whether
32b70 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 the statement w
32b80 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e as prepared usin
32b90 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 58 22 g the newer "vX"
32ba0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 5b interfaces.** [
32bb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
32bc0 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f v3()], [sqlite3_
32bd0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b prepare_v2()], [
32be0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
32bf0 36 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 6_v3()],.** [sql
32c00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
32c10 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 2()] or the olde
32c20 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 r legacy.** inte
32c30 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f rfaces [sqlite3_
32c40 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b prepare()] and [
32c50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
32c60 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 6()]. The use o
32c70 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 58 f the.** new "vX
32c80 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 " interface is r
32c90 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e ecommended for n
32ca0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ew applications
32cb0 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a but the legacy.*
32cc0 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c * interface will
32cd0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 continue to be
32ce0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a supported..**.**
32cf0 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 ^In the legacy
32d00 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 interface, the r
32d10 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c eturn value will
32d20 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 be either [SQLI
32d30 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 TE_BUSY],.** [SQ
32d40 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c LITE_DONE], [SQL
32d50 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 ITE_ROW], [SQLIT
32d60 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 E_ERROR], or [SQ
32d70 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a LITE_MISUSE]..**
32d80 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 ^With the "v2"
32d90 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f interface, any o
32da0 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 f the other [res
32db0 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a ult codes] or.**
32dc0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
32dd0 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 t codes] might b
32de0 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 e returned as we
32df0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 ll..**.** ^[SQLI
32e00 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 TE_BUSY] means t
32e10 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 hat the database
32e20 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 engine was unab
32e30 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 le to acquire th
32e40 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f e.** database lo
32e50 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 cks it needs to
32e60 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 do its job. ^If
32e70 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
32e80 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 s a [COMMIT].**
32e90 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 or occurs outsid
32ea0 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 e of an explicit
32eb0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 transaction, th
32ec0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 en you can retry
32ed0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e the.** statemen
32ee0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 t. If the state
32ef0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 ment is not a [C
32f00 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 OMMIT] and occur
32f10 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 s within an.** e
32f20 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
32f30 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f ion then you sho
32f40 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 uld rollback the
32f50 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 transaction bef
32f60 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e ore.** continuin
32f70 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 g..**.** ^[SQLIT
32f80 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 E_DONE] means th
32f90 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 at the statement
32fa0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 has finished ex
32fb0 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 ecuting.** succe
32fc0 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 ssfully. sqlite
32fd0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 3_step() should
32fe0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 not be called ag
32ff0 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 ain on this virt
33000 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 ual.** machine w
33010 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c ithout first cal
33020 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 ling [sqlite3_re
33030 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 set()] to reset
33040 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d the virtual.** m
33050 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 achine back to i
33060 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 ts initial state
33070 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
33080 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 SQL statement be
33090 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 ing executed ret
330a0 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 urns any data, t
330b0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d hen [SQLITE_ROW]
330c0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
330d0 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 each time a new
330e0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 row of data is r
330f0 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 eady for process
33100 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 ing by the.** ca
33110 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 ller. The values
33120 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 may be accessed
33130 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 using the [colu
33140 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 mn access functi
33150 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 ons]..** sqlite3
33160 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 _step() is calle
33170 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 d again to retri
33180 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 eve the next row
33190 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 of data..**.**
331a0 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 ^[SQLITE_ERROR]
331b0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e means that a run
331c0 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 -time error (suc
331d0 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e h as a constrain
331e0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 t.** violation)
331f0 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 has occurred. s
33200 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 qlite3_step() sh
33210 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c ould not be call
33220 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 ed again on.** t
33230 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f he VM. More info
33240 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 rmation may be f
33250 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 ound by calling
33260 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
33270 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 )]..** ^With the
33280 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
33290 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 e, a more specif
332a0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 ic error code (f
332b0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b or example,.** [
332c0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
332d0 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d ], [SQLITE_SCHEM
332e0 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 A], [SQLITE_CORR
332f0 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 UPT], and so for
33300 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 th).** can be ob
33310 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e tained by callin
33320 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
33330 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 ()] on the.** [p
33340 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
33350 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 t]. ^In the "v2
33360 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 " interface,.**
33370 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 the more specifi
33380 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 c error code is
33390 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c returned directl
333a0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 y by sqlite3_ste
333b0 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 p()..**.** [SQLI
333c0 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 TE_MISUSE] means
333d0 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 that the this r
333e0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 outine was calle
333f0 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c d inappropriatel
33400 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 y..** Perhaps it
33410 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 was called on a
33420 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
33430 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a ment] that has.*
33440 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b * already been [
33450 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
33460 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 | finalized] or
33470 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 on one that had
33480 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 .** previously r
33490 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
334a0 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 ERROR] or [SQLIT
334b0 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 E_DONE]. Or it
334c0 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 could.** be the
334d0 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 case that the sa
334e0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
334f0 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 ection is being
33500 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a used by two or.*
33510 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 * more threads a
33520 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e t the same momen
33530 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a t in time..**.**
33540 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e For all version
33550 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 s of SQLite up t
33560 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 o and including
33570 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 3.6.23.1, a call
33580 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
33590 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 reset()] was req
335a0 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 uired after sqli
335b0 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 te3_step() retur
335c0 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 ned anything.**
335d0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
335e0 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 TE_ROW] before a
335f0 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e ny subsequent in
33600 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 vocation of.** s
33610 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
33620 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 Failure to reset
33630 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
33640 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a atement using .*
33650 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
33660 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 ()] would result
33670 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d in an [SQLITE_M
33680 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 ISUSE] return fr
33690 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 om.** sqlite3_st
336a0 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 ep(). But after
336b0 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 [version 3.6.23
336c0 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 .1] ([dateof:3.6
336d0 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 .23.1],.** sqlit
336e0 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a e3_step() began.
336f0 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 ** calling [sqli
33700 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 te3_reset()] aut
33710 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 omatically in th
33720 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 is circumstance
33730 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 rather.** than r
33740 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 eturning [SQLITE
33750 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 _MISUSE]. This
33760 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 is not considere
33770 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 d a compatibilit
33780 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 y.** break becau
33790 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 se any applicati
337a0 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 on that ever rec
337b0 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f eives an SQLITE_
337c0 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 MISUSE error.**
337d0 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 is broken by def
337e0 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 inition. The [S
337f0 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 QLITE_OMIT_AUTOR
33800 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 ESET] compile-ti
33810 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e me option.** can
33820 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 be used to rest
33830 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 ore the legacy b
33840 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c ehavior..**.** <
33850 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 b>Goofy Interfac
33860 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 e Alert:</b> In
33870 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 the legacy inter
33880 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 face, the sqlite
33890 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 3_step().** API
338a0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 always returns a
338b0 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 generic error c
338c0 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 ode, [SQLITE_ERR
338d0 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 OR], following a
338e0 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 ny.** error othe
338f0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 r than [SQLITE_B
33900 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 USY] and [SQLITE
33910 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d _MISUSE]. You m
33920 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c ust call.** [sql
33930 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
33940 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
33950 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 ze()] in order t
33960 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 o find one of th
33970 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 e.** specific [e
33980 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 rror codes] that
33990 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 better describe
339a0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 s the error..**
339b0 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 We admit that th
339c0 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 is is a goofy de
339d0 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c sign. The probl
339e0 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 em has been fixe
339f0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 d.** with the "v
33a00 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 2" interface. I
33a10 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c f you prepare al
33a20 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 l of your SQL st
33a30 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e atements.** usin
33a40 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
33a50 72 65 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71 6c re_v3()] or [sql
33a60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
33a70 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 )].** or [sqlite
33a80 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
33a90 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ] or [sqlite3_pr
33aa0 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e epare16_v3()] in
33ab0 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 stead.** of the
33ac0 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f legacy [sqlite3_
33ad0 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b prepare()] and [
33ae0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
33af0 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 6()] interfaces,
33b00 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 .** then the mor
33b10 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f e specific [erro
33b20 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 r codes] are ret
33b30 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a urned directly.*
33b40 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 * by sqlite3_ste
33b50 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 p(). The use of
33b60 20 74 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 the "vX" interf
33b70 61 63 65 73 20 69 73 20 72 65 63 6f 6d 6d 65 6e aces is recommen
33b80 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ded..*/.int sqli
33b90 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 te3_step(sqlite3
33ba0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
33bb0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
33bc0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 of columns in a
33bd0 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d result set.** M
33be0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
33bf0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 tmt.**.** ^The s
33c00 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
33c10 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 t(P) interface r
33c20 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
33c30 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
33c40 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 the.** current r
33c50 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ow of the result
33c60 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 set of [prepare
33c70 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a d statement] P..
33c80 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 ** ^If prepared
33c90 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 statement P does
33ca0 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 not have result
33cb0 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 s ready to retur
33cc0 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 n.** (via calls
33cd0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
33ce0 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c column_int | sql
33cf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d ite3_column_*()]
33d00 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 of.** interface
33d10 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f s) then sqlite3_
33d20 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 data_count(P) re
33d30 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 turns 0..** ^The
33d40 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
33d50 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 unt(P) routine a
33d60 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 lso returns 0 if
33d70 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 P is a NULL poi
33d80 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 nter..** ^The sq
33d90 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
33da0 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 (P) routine retu
33db0 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 rns 0 if the pre
33dc0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a vious call to.**
33dd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 [sqlite3_step](
33de0 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c P) returned [SQL
33df0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 ITE_DONE]. ^The
33e00 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
33e10 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 unt(P).** will r
33e20 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 eturn non-zero i
33e30 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 f previous call
33e40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
33e50 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a ](P) returned.**
33e60 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 [SQLITE_ROW], e
33e70 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 xcept in the cas
33e80 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 e of the [PRAGMA
33e90 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 incremental_vac
33ea0 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 uum].** where it
33eb0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
33ec0 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 zero since each
33ed0 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c step of that mul
33ee0 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d ti-step.** pragm
33ef0 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 a returns 0 colu
33f00 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a mns of data..**.
33f10 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
33f20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 lite3_column_cou
33f30 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c nt()].*/.int sql
33f40 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
33f50 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
33f60 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
33f70 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 I3REF: Fundament
33f80 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 al Datatypes.**
33f90 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 KEYWORDS: SQLITE
33fa0 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 _TEXT.**.** ^(Ev
33fb0 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c ery value in SQL
33fc0 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 ite has one of f
33fd0 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 ive fundamental
33fe0 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a datatypes:.**.**
33ff0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 <ul>.** <li> 64
34000 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
34010 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 ger.** <li> 64-b
34020 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 it IEEE floating
34030 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a point number.**
34040 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 <li> string.**
34050 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 <li> BLOB.** <li
34060 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 > NULL.** </ul>)
34070 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f ^.**.** These co
34080 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 nstants are code
34090 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 s for each of th
340a0 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a ose types..**.**
340b0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 Note that the S
340c0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 QLITE_TEXT const
340d0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 ant was also use
340e0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 d in SQLite vers
340f0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 ion 2.** for a c
34100 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 ompletely differ
34110 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f ent meaning. So
34120 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b ftware that link
34130 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a s against both.*
34140 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e * SQLite version
34150 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 2 and SQLite ve
34160 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 rsion 3 should u
34170 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c se SQLITE3_TEXT,
34180 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 not.** SQLITE_T
34190 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 EXT..*/.#define
341a0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 SQLITE_INTEGER
341b0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
341c0 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 _FLOAT 2.#def
341d0 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 ine SQLITE_BLOB
341e0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
341f0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a LITE_NULL 5.
34200 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 #ifdef SQLITE_TE
34210 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 XT.# undef SQLIT
34220 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 E_TEXT.#else.# d
34230 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 efine SQLITE_TEX
34240 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 T 3.#endif.#
34250 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 define SQLITE3_T
34260 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a EXT 3../*.**
34270 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c CAPI3REF: Resul
34280 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 t Values From A
34290 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 Query.** KEYWORD
342a0 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 S: {column acces
342b0 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 s functions}.**
342c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
342d0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 stmt.**.** <b>Su
342e0 6d 6d 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 mmary:</b>.** <b
342f0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65 lockquote><table
34300 20 62 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70 61 border=0 cellpa
34310 64 64 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61 63 dding=0 cellspac
34320 69 6e 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 ing=0>.** <tr><t
34330 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c d><b>sqlite3_col
34340 75 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e umn_blob</b><td>
34350 26 72 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20 72 →<td>BLOB r
34360 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 esult.** <tr><td
34370 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ><b>sqlite3_colu
34380 6d 6e 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64 mn_double</b><td
34390 3e 26 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c 20 >→<td>REAL
343a0 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 result.** <tr><t
343b0 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c d><b>sqlite3_col
343c0 75 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26 umn_int</b><td>&
343d0 72 61 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74 20 rarr;<td>32-bit
343e0 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a INTEGER result.*
343f0 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c * <tr><td><b>sql
34400 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 ite3_column_int6
34410 34 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 4</b><td>→<
34420 74 64 3e 36 34 2d 62 69 74 20 49 4e 54 45 47 45 td>64-bit INTEGE
34430 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e R result.** <tr>
34440 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 <td><b>sqlite3_c
34450 6f 6c 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74 olumn_text</b><t
34460 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d d>→<td>UTF-
34470 38 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 8 TEXT result.**
34480 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 <tr><td><b>sqli
34490 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
344a0 36 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 6</b><td>→<
344b0 74 64 3e 55 54 46 2d 31 36 20 54 45 58 54 20 72 td>UTF-16 TEXT r
344c0 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 esult.** <tr><td
344d0 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ><b>sqlite3_colu
344e0 6d 6e 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e mn_value</b><td>
344f0 26 72 61 72 72 3b 3c 74 64 3e 54 68 65 20 72 65 →<td>The re
34500 73 75 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20 5b sult as an .** [
34510 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75 6e sqlite3_value|un
34520 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
34530 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 3_value] object.
34540 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62 73 .** <tr><td>&nbs
34550 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e p;<td> <td>
34560 26 6e 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 .** <tr><t
34570 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c d><b>sqlite3_col
34580 75 6d 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74 64 umn_bytes</b><td
34590 3e 26 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65 20 >→<td>Size
345a0 6f 66 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20 of a BLOB.** or
345b0 61 20 55 54 46 2d 38 20 54 45 58 54 20 72 65 73 a UTF-8 TEXT res
345c0 75 6c 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 ult in bytes.**
345d0 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 <tr><td><b>sqlit
345e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
345f0 36 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f 62 6 </b
34600 3e 0a 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b 26 >.** <td>→&
34610 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e 53 nbsp; <td>S
34620 69 7a 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a 2a ize of UTF-16.**
34630 20 54 45 58 54 20 69 6e 20 62 79 74 65 73 0a 2a TEXT in bytes.*
34640 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c * <tr><td><b>sql
34650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
34660 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 </b><td>→<t
34670 64 3e 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61 74 d>Default.** dat
34680 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 atype of the res
34690 75 6c 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c ult.** </table><
346a0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
346b0 2a 2a 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c 2f ** <b>Details:</
346c0 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 b>.**.** ^These
346d0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
346e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 information abou
346f0 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d t a single colum
34700 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 n of the current
34710 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f .** result row o
34720 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 f a query. ^In
34730 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 every case the f
34740 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
34750 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
34760 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
34770 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 tatement] that i
34780 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 s being evaluate
34790 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f d (the [sqlite3_
347a0 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 stmt*].** that w
347b0 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d as returned from
347c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
347d0 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f e_v2()] or one o
347e0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a f its variants).
347f0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e ** and the secon
34800 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
34810 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 e index of the c
34820 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 olumn for which
34830 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 information.** s
34840 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 hould be returne
34850 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 d. ^The leftmost
34860 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 column of the r
34870 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 esult set has th
34880 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 e index 0..** ^T
34890 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
348a0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 umns in the resu
348b0 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d lt can be determ
348c0 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 ined using.** [s
348d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f qlite3_column_co
348e0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 unt()]..**.** If
348f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
34900 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 nt does not curr
34910 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 ently point to a
34920 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 valid row, or i
34930 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 f the.** column
34940 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
34950 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c range, the resul
34960 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a t is undefined..
34970 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
34980 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 s may only be ca
34990 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f lled when the mo
349a0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
349b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 o.** [sqlite3_st
349c0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e ep()] has return
349d0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 ed [SQLITE_ROW]
349e0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b and neither.** [
349f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
34a00 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 nor [sqlite3_fi
34a10 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 nalize()] have b
34a20 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 een called subse
34a30 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 quently..** If a
34a40 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
34a50 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
34a60 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 after [sqlite3_r
34a70 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
34a80 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
34a90 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c )] or after [sql
34aa0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
34ab0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d returned.** som
34ac0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 ething other tha
34ad0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 n [SQLITE_ROW],
34ae0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
34af0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 undefined..** If
34b00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
34b10 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
34b20 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
34b30 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a e3_finalize()].*
34b40 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f * are called fro
34b50 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 m a different th
34b60 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f read while any o
34b70 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
34b80 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c .** are pending,
34b90 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
34ba0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
34bb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
34bc0 20 73 69 78 20 69 6e 74 65 72 66 61 63 65 73 20 six interfaces
34bd0 28 5f 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c (_blob, _double,
34be0 20 5f 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20 5f _int, _int64, _
34bf0 74 65 78 74 2c 20 61 6e 64 20 5f 74 65 78 74 31 text, and _text1
34c00 36 29 0a 2a 2a 20 65 61 63 68 20 72 65 74 75 72 6).** each retur
34c10 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 n the value of a
34c20 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 result column i
34c30 6e 20 61 20 73 70 65 63 69 66 69 63 20 64 61 74 n a specific dat
34c40 61 20 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a 2a a format. If.**
34c50 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 the result colu
34c60 6d 6e 20 69 73 20 6e 6f 74 20 69 6e 69 74 69 61 mn is not initia
34c70 6c 6c 79 20 69 6e 20 74 68 65 20 72 65 71 75 65 lly in the reque
34c80 73 74 65 64 20 66 6f 72 6d 61 74 20 28 66 6f 72 sted format (for
34c90 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20 example,.** if
34ca0 74 68 65 20 71 75 65 72 79 20 72 65 74 75 72 6e the query return
34cb0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 62 75 74 s an integer but
34cc0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c the sqlite3_col
34cd0 75 6d 6e 5f 74 65 78 74 28 29 20 69 6e 74 65 72 umn_text() inter
34ce0 66 61 63 65 0a 2a 2a 20 69 73 20 75 73 65 64 20 face.** is used
34cf0 74 6f 20 65 78 74 72 61 63 74 20 74 68 65 20 76 to extract the v
34d00 61 6c 75 65 29 20 74 68 65 6e 20 61 6e 20 61 75 alue) then an au
34d10 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e tomatic type con
34d20 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f version is perfo
34d30 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 rmed..**.** ^The
34d40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
34d50 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 type() routine r
34d60 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 eturns the.** [S
34d70 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 QLITE_INTEGER |
34d80 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 datatype code] f
34d90 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 or the initial d
34da0 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 ata type.** of t
34db0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e he result column
34dc0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 . ^The returned
34dd0 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 value is one of
34de0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
34df0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c ],.** [SQLITE_FL
34e00 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 OAT], [SQLITE_TE
34e10 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f XT], [SQLITE_BLO
34e20 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e B], or [SQLITE_N
34e30 55 4c 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 74 ULL]..** The ret
34e40 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 73 71 6c urn value of sql
34e50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
34e60 28 29 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 () can be used t
34e70 6f 20 64 65 63 69 64 65 20 77 68 69 63 68 0a 2a o decide which.*
34e80 2a 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 73 * of the first s
34e90 69 78 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f ix interface sho
34ea0 75 6c 64 20 62 65 20 75 73 65 64 20 74 6f 20 65 uld be used to e
34eb0 78 74 72 61 63 74 20 74 68 65 20 63 6f 6c 75 6d xtract the colum
34ec0 6e 20 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 n value..** The
34ed0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
34ee0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
34ef0 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 _type() is only
34f00 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f meaningful if no
34f10 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20 74 79 .** automatic ty
34f20 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 pe conversions h
34f30 61 76 65 20 6f 63 63 75 72 72 65 64 20 66 6f 72 ave occurred for
34f40 20 74 68 65 20 76 61 6c 75 65 20 69 6e 20 71 75 the value in qu
34f50 65 73 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74 estion. .** Aft
34f60 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 er a type conver
34f70 73 69 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c 74 sion, the result
34f80 20 6f 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 of calling sqli
34f90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
34fa0 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 ).** is undefine
34fb0 64 2c 20 74 68 6f 75 67 68 20 68 61 72 6d 6c 65 d, though harmle
34fc0 73 73 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 ss. Future.** v
34fd0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
34fe0 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 e may change the
34ff0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c behavior of sql
35000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
35010 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ().** following
35020 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f a type conversio
35030 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 n..**.** If the
35040 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 result is a BLOB
35050 20 6f 72 20 61 20 54 45 58 54 20 73 74 72 69 6e or a TEXT strin
35060 67 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 g, then the sqli
35070 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
35080 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
35090 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
350a0 29 20 69 6e 74 65 72 66 61 63 65 73 20 63 61 6e ) interfaces can
350b0 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 74 65 be used to dete
350c0 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 0a 2a rmine the size.*
350d0 2a 20 6f 66 20 74 68 61 74 20 42 4c 4f 42 20 6f * of that BLOB o
350e0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 r string..**.**
350f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
35100 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
35110 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 8 string then th
35120 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
35130 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 _bytes().** rout
35140 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
35150 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
35160 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 in that BLOB or
35170 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
35180 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 he result is a U
35190 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 TF-16 string, th
351a0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
351b0 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 n_bytes() conver
351c0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 ts.** the string
351d0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 to UTF-8 and th
351e0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e en returns the n
351f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a umber of bytes..
35200 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
35210 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 t is a numeric v
35220 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 alue then sqlite
35230 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
35240 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 uses.** [sqlite
35250 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 3_snprintf()] to
35260 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 convert that va
35270 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 lue to a UTF-8 s
35280 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
35290 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
352a0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
352b0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
352c0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 the result is NU
352d0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 LL, then sqlite3
352e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
352f0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
35300 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
35310 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 lt is a BLOB or
35320 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 UTF-16 string th
35330 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 en the sqlite3_c
35340 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a olumn_bytes16().
35350 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
35360 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
35370 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 bytes in that B
35380 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a LOB or string..*
35390 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
353a0 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 is a UTF-8 stri
353b0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ng, then sqlite3
353c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
353d0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 ) converts.** th
353e0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d e string to UTF-
353f0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 16 and then retu
35400 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
35410 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 f bytes..** ^If
35420 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
35430 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 numeric value th
35440 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
35450 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 n_bytes16() uses
35460 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 .** [sqlite3_snp
35470 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 rintf()] to conv
35480 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 ert that value t
35490 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e o a UTF-16 strin
354a0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a g and returns.**
354b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
354c0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 ytes in that str
354d0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
354e0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 result is NULL,
354f0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
35500 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 umn_bytes16() re
35510 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a turns zero..**.*
35520 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 * ^The values re
35530 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
35540 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
35550 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 )] and .** [sqli
35560 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
35570 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 16()] do not inc
35580 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 lude the zero te
35590 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 rminators at the
355a0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 end.** of the s
355b0 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 tring. ^For cla
355c0 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 rity: the values
355d0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
355e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
355f0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 bytes()] and [sq
35600 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
35610 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 es16()] are the
35620 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 number of.** byt
35630 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 es in the string
35640 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
35650 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a of characters..
35660 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 **.** ^Strings r
35670 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
35680 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
35690 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
356a0 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a umn_text16(),.**
356b0 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 even empty stri
356c0 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 ngs, are always
356d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e zero-terminated.
356e0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a ^The return.**
356f0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
35700 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
35710 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e ) for a zero-len
35720 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 gth BLOB is a NU
35730 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
35740 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 * <b>Warning:</b
35750 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 > ^The object re
35760 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
35770 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
35780 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 )] is an.** [unp
35790 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
357a0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 _value] object.
357b0 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 In a multithrea
357c0 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c ded environment,
357d0 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 .** an unprotect
357e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
357f0 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 object may only
35800 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 be used safely
35810 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 with.** [sqlite3
35820 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 _bind_value()] a
35830 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 nd [sqlite3_resu
35840 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 lt_value()]..**
35850 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 If the [unprotec
35860 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
35870 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e e] object return
35880 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 ed by.** [sqlite
35890 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 3_column_value()
358a0 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 ] is used in any
358b0 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c other way, incl
358c0 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 uding calls.** t
358d0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 o routines like
358e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 [sqlite3_value_i
358f0 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f nt()], [sqlite3_
35900 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a value_text()],.*
35910 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 * or [sqlite3_va
35920 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 lue_bytes()], th
35930 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f e behavior is no
35940 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a t threadsafe..**
35950 20 48 65 6e 63 65 2c 20 74 68 65 20 73 71 6c 69 Hence, the sqli
35960 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
35970 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 () interface.**
35980 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 is normally only
35990 20 75 73 65 66 75 6c 20 77 69 74 68 69 6e 20 74 useful within t
359a0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
359b0 6e 20 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69 63 n of .** [applic
359c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
359d0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 20 L functions] or
359e0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d [virtual tables]
359f0 2c 20 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a 20 , not within.**
35a00 74 6f 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69 63 top-level applic
35a10 61 74 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a ation code..**.*
35a20 2a 20 54 68 65 20 74 68 65 73 65 20 72 6f 75 74 * The these rout
35a30 69 6e 65 73 20 6d 61 79 20 61 74 74 65 6d 70 74 ines may attempt
35a40 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
35a50 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 datatype of the
35a60 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20 result..** ^For
35a70 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 example, if the
35a80 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
35a90 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 ntation is FLOAT
35aa0 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 and a text resu
35ab0 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 lt.** is request
35ac0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 ed, [sqlite3_snp
35ad0 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 rintf()] is used
35ae0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 internally to p
35af0 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f erform the.** co
35b00 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 nversion automat
35b10 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 ically. ^(The f
35b20 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 ollowing table d
35b30 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 etails the conve
35b40 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 rsions.** that a
35b50 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a re applied:.**.*
35b60 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a * <blockquote>.*
35b70 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d * <table border=
35b80 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e "1">.** <tr><th>
35b90 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 Internal<br>Typ
35ba0 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 e <th> Requested
35bb0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 <br>Type <th> C
35bc0 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 onversion.**.**
35bd0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
35be0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
35bf0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
35c00 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 0.** <tr><td> N
35c10 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f ULL <td> FLO
35c20 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c AT <td> Resul
35c30 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e t is 0.0.** <tr>
35c40 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
35c50 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 d> TEXT <td
35c60 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 > Result is a NU
35c70 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 LL pointer.** <t
35c80 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
35c90 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
35ca0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 td> Result is a
35cb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
35cc0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
35cd0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
35ce0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 <td> Convert fr
35cf0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c om integer to fl
35d00 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 oat.** <tr><td>
35d10 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 INTEGER <td>
35d20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 TEXT <td> ASC
35d30 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 II rendering of
35d40 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c the integer.** <
35d50 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
35d60 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
35d70 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 <td> Same as INT
35d80 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 EGER->TEXT.** <t
35d90 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 r><td> FLOAT
35da0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
35db0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e td> [CAST] to IN
35dc0 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 TEGER.** <tr><td
35dd0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
35de0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
35df0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f SCII rendering o
35e00 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c f the float.** <
35e10 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 tr><td> FLOAT
35e20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
35e30 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 <td> [CAST] to B
35e40 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 LOB.** <tr><td>
35e50 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e TEXT <td> IN
35e60 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 TEGER <td> [CA
35e70 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a ST] to INTEGER.*
35e80 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
35e90 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <td> FLOAT
35ea0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 <td> [CAST] t
35eb0 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 o REAL.** <tr><t
35ec0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
35ed0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
35ee0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 No change.** <tr
35ef0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c ><td> BLOB <
35f00 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
35f10 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 d> [CAST] to INT
35f20 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e EGER.** <tr><td>
35f30 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 BLOB <td>
35f40 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 FLOAT <td> [C
35f50 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 AST] to REAL.**
35f60 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
35f70 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
35f80 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f <td> Add a zero
35f90 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e terminator if n
35fa0 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 eeded.** </table
35fb0 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 >.** </blockquot
35fc0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 e>)^.**.** Note
35fd0 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 that when type c
35fe0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 onversions occur
35ff0 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 , pointers retur
36000 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 ned by prior.**
36010 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
36020 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 _column_blob(),
36030 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
36040 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a ext(), and/or.**
36050 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
36060 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 text16() may be
36070 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 invalidated..**
36080 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 Type conversions
36090 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 and pointer inv
360a0 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 alidations might
360b0 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 occur.** in the
360c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 following cases
360d0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
360e0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c <li> The initial
360f0 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c content is a BL
36100 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 OB and sqlite3_c
36110 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a olumn_text() or.
36120 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f ** sqlite3_
36130 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
36140 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 is called. A ze
36150 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 ro-terminator mi
36160 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 ght.** need
36170 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 to be added to
36180 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e the string.</li>
36190 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 .** <li> The ini
361a0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 tial content is
361b0 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 UTF-8 text and s
361c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
361d0 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 tes16() or.**
361e0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d sqlite3_colum
361f0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 n_text16() is ca
36200 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 lled. The conte
36210 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 nt must be conve
36220 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 rted.** to
36230 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 UTF-16.</li>.**
36240 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c <li> The initial
36250 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d content is UTF-
36260 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 16 text and sqli
36270 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
36280 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
36290 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
362a0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 t() is called.
362b0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 The content must
362c0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a be converted.**
362d0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c to UTF-8.<
362e0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a /li>.** </ul>.**
362f0 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 .** ^Conversions
36300 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 between UTF-16b
36310 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 e and UTF-16le a
36320 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 re always done i
36330 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a n place and do.*
36340 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 * not invalidate
36350 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 a prior pointer
36360 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 , though of cour
36370 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f se the content o
36380 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 f the buffer.**
36390 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 that the prior p
363a0 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 ointer reference
363b0 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e s will have been
363c0 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 modified. Othe
363d0 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f r kinds.** of co
363e0 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e nversion are don
363f0 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 e in place when
36400 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 it is possible,
36410 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 but sometimes th
36420 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f ey.** are not po
36430 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 ssible and in th
36440 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 ose cases prior
36450 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 pointers are inv
36460 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 alidated..**.**
36470 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 The safest polic
36480 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 y is to invoke t
36490 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a hese routines.**
364a0 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 in one of the f
364b0 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a ollowing ways:.*
364c0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c *.** <ul>.** <l
364d0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e i>sqlite3_column
364e0 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 _text() followed
364f0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
36500 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a mn_bytes()</li>.
36510 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f ** <li>sqlite3_
36520 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f column_blob() fo
36530 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 llowed by sqlite
36540 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
36550 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 </li>.** <li>sq
36560 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
36570 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 t16() followed b
36580 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
36590 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a _bytes16()</li>.
365a0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 ** </ul>.**.** I
365b0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 n other words, y
365c0 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 ou should call s
365d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
365e0 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 xt(),.** sqlite3
365f0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 _column_blob(),
36600 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
36610 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 n_text16() first
36620 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 to force the re
36630 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 sult.** into the
36640 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c desired format,
36650 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c then invoke sql
36660 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
36670 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 s() or.** sqlite
36680 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
36690 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 () to find the s
366a0 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ize of the resul
366b0 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 t. Do not mix c
366c0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 alls.** to sqlit
366d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
366e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
366f0 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 mn_blob() with c
36700 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 alls to.** sqlit
36710 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
36720 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6(), and do not
36730 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c mix calls to sql
36740 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
36750 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 16().** with cal
36760 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ls to sqlite3_co
36770 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a lumn_bytes()..**
36780 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 .** ^The pointer
36790 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 s returned are v
367a0 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 alid until a typ
367b0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 e conversion occ
367c0 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 urs as.** descri
367d0 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e bed above, or un
367e0 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 til [sqlite3_ste
367f0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 p()] or [sqlite3
36800 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 _reset()] or.**
36810 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
36820 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 e()] is called.
36830 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 ^The memory spa
36840 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 ce used to hold
36850 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 strings.** and B
36860 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 LOBs is freed au
36870 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f tomatically. Do
36880 20 6e 6f 74 20 70 61 73 73 20 74 68 65 20 70 6f not pass the po
36890 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a inters returned.
368a0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ** from [sqlite3
368b0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c _column_blob()],
368c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
368d0 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 _text()], etc. i
368e0 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nto.** [sqlite3_
368f0 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e free()]..**.** ^
36900 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c (If a memory all
36910 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 ocation error oc
36920 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 curs during the
36930 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e evaluation of an
36940 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f y.** of these ro
36950 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c utines, a defaul
36960 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 t value is retur
36970 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c ned. The defaul
36980 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 t value.** is ei
36990 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 ther the integer
369a0 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 0, the floating
369b0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e point number 0.
369c0 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 0, or a NULL.**
369d0 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 pointer. Subseq
369e0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 uent calls to [s
369f0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
36a00 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a ] will return.**
36a10 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e [SQLITE_NOMEM].
36a20 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 )^.*/.const void
36a30 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
36a40 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 _blob(sqlite3_st
36a50 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
36a60 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 double sqlite3_c
36a70 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c olumn_double(sql
36a80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
36a90 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 iCol);.int sqlit
36aa0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 e3_column_int(sq
36ab0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
36ac0 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f iCol);.sqlite3_
36ad0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f int64 sqlite3_co
36ae0 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 lumn_int64(sqlit
36af0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
36b00 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 ol);.const unsig
36b10 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 ned char *sqlite
36b20 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 3_column_text(sq
36b30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
36b40 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f iCol);.const vo
36b50 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
36b60 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 mn_text16(sqlite
36b70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
36b80 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 l);.sqlite3_valu
36b90 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e *sqlite3_colum
36ba0 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f n_value(sqlite3_
36bb0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
36bc0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f ;.int sqlite3_co
36bd0 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 lumn_bytes(sqlit
36be0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
36bf0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ol);.int sqlite3
36c00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
36c10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
36c20 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 nt iCol);.int sq
36c30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
36c40 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
36c50 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a int iCol);../*.
36c60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 ** CAPI3REF: Des
36c70 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 troy A Prepared
36c80 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
36c90 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 .** DESTRUCTOR:
36ca0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
36cb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
36cc0 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 finalize() funct
36cd0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f ion is called to
36ce0 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 delete a [prepa
36cf0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
36d00 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 ** ^If the most
36d10 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f recent evaluatio
36d20 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 n of the stateme
36d30 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e nt encountered n
36d40 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 o errors.** or i
36d50 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
36d60 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 is never been ev
36d70 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 aluated, then sq
36d80 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
36d90 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 returns.** SQLI
36da0 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 TE_OK. ^If the
36db0 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c most recent eval
36dc0 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d uation of statem
36dd0 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 ent S failed, th
36de0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 en.** sqlite3_fi
36df0 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e nalize(S) return
36e00 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 s the appropriat
36e10 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f e [error code] o
36e20 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 r.** [extended e
36e30 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a rror code]..**.*
36e40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 * ^The sqlite3_f
36e50 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 inalize(S) routi
36e60 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 ne can be called
36e70 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 at any point du
36e80 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 ring.** the life
36e90 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 cycle of [prepa
36ea0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
36eb0 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 :.** before stat
36ec0 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 ement S is ever
36ed0 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 evaluated, after
36ee0 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 .** one or more
36ef0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
36f00 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 3_reset()], or a
36f10 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a fter any call.**
36f20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
36f30 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 p()] regardless
36f40 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
36f50 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 t the statement
36f60 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 has.** completed
36f70 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a execution..**.*
36f80 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 * ^Invoking sqli
36f90 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f te3_finalize() o
36fa0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 n a NULL pointer
36fb0 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e is a harmless n
36fc0 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 o-op..**.** The
36fd0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
36fe0 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 finalize every
36ff0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
37000 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f ent] in order to
37010 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 avoid.** resour
37020 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 ce leaks. It is
37030 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f a grievous erro
37040 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 r for the applic
37050 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 ation to try to
37060 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 use.** a prepare
37070 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 d statement afte
37080 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 r it has been fi
37090 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 nalized. Any us
370a0 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a e of a prepared.
370b0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 ** statement aft
370c0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 er it has been f
370d0 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 inalized can res
370e0 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 ult in undefined
370f0 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 and.** undesira
37100 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 ble behavior suc
37110 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 h as segfaults a
37120 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 nd heap corrupti
37130 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 on..*/.int sqlit
37140 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 e3_finalize(sqli
37150 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
37160 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
37170 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 F: Reset A Prepa
37180 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 red Statement Ob
37190 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ject.** METHOD:
371a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
371b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
371c0 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 eset() function
371d0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 is called to res
371e0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 et a [prepared s
371f0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a tatement].** obj
37200 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 ect back to its
37210 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 initial state, r
37220 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 eady to be re-ex
37230 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 ecuted..** ^Any
37240 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 SQL statement va
37250 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 riables that had
37260 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f values bound to
37270 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 them using.** t
37280 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 he [sqlite3_bind
37290 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f _blob | sqlite3_
372a0 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 bind_*() API] re
372b0 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 tain their value
372c0 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 s..** Use [sqlit
372d0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 e3_clear_binding
372e0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 s()] to reset th
372f0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a e bindings..**.*
37300 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
37310 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 reset(S)] interf
37320 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b ace resets the [
37330 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
37340 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f nt] S.** back to
37350 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f the beginning o
37360 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a f its program..*
37370 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 *.** ^If the mos
37380 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
37390 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
373a0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 )] for the.** [p
373b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
373c0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 t] S returned [S
373d0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 QLITE_ROW] or [S
373e0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 QLITE_DONE],.**
373f0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 or if [sqlite3_s
37400 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 tep(S)] has neve
37410 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 r before been ca
37420 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 lled on S,.** th
37430 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 en [sqlite3_rese
37440 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 t(S)] returns [S
37450 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a QLITE_OK]..**.**
37460 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ^If the most re
37470 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 cent call to [sq
37480 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 lite3_step(S)] f
37490 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 or the.** [prepa
374a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
374b0 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 indicated an er
374c0 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 ror, then.** [sq
374d0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
374e0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f returns an appro
374f0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f priate [error co
37500 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 de]..**.** ^The
37510 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
37520 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 )] interface doe
37530 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 s not change the
37540 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e values.** of an
37550 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f y [sqlite3_bind_
37560 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f blob|bindings] o
37570 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 n the [prepared
37580 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f statement] S..*/
37590 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 .int sqlite3_res
375a0 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 et(sqlite3_stmt
375b0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
375c0 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 CAPI3REF: Create
375d0 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c Or Redefine SQL
375e0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 Functions.** KE
375f0 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f YWORDS: {functio
37600 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 n creation routi
37610 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 nes}.** KEYWORDS
37620 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 : {application-d
37630 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
37640 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ion}.** KEYWORDS
37650 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 : {application-d
37660 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
37670 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a ions}.** METHOD:
37680 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
37690 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
376a0 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e (collectively kn
376b0 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e own as "function
376c0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e creation routin
376d0 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 es").** are used
376e0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 to add SQL func
376f0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 tions or aggrega
37700 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 tes or to redefi
37710 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a ne the behavior.
37720 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 ** of existing S
37730 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 QL functions or
37740 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 aggregates. The
37750 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 only difference
37760 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 s between.** the
37770 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
37780 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e the text encodin
37790 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a g expected for.*
377a0 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 * the second par
377b0 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 ameter (the name
377c0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e of the function
377d0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a being created).
377e0 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 ** and the prese
377f0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f nce or absence o
37800 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 f a destructor c
37810 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 allback for.** t
37820 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
37830 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ata pointer..**.
37840 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 ** ^The first pa
37850 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b rameter is the [
37860 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
37870 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 ion] to which th
37880 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f e SQL.** functio
37890 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 n is to be added
378a0 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 . ^If an applic
378b0 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 ation uses more
378c0 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 than one databas
378d0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e.** connection
378e0 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e then application
378f0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
37900 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 ctions must be a
37910 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 dded.** to each
37920 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
37930 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a ion separately..
37940 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e **.** ^The secon
37950 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
37960 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 he name of the S
37970 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 QL function to b
37980 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 e created or.**
37990 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 redefined. ^The
379a0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e length of the n
379b0 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 ame is limited t
379c0 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 o 255 bytes in a
379d0 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 UTF-8.** repres
379e0 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 entation, exclus
379f0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d ive of the zero-
37a00 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f terminator. ^No
37a10 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 te that the name
37a20 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 .** length limit
37a30 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 is in UTF-8 byt
37a40 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 es, not characte
37a50 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 rs nor UTF-16 by
37a60 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 tes. .** ^Any a
37a70 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 ttempt to create
37a80 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 a function with
37a90 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a a longer name.*
37aa0 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e * will result in
37ab0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
37ac0 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e being returned.
37ad0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 .**.** ^The thir
37ae0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 d parameter (nAr
37af0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d g).** is the num
37b00 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 ber of arguments
37b10 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 that the SQL fu
37b20 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 nction or.** agg
37b30 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 regate takes. ^I
37b40 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 f this parameter
37b50 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 is -1, then the
37b60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 SQL function or
37b70 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 .** aggregate ma
37b80 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 y take any numbe
37b90 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 r of arguments b
37ba0 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 etween 0 and the
37bb0 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 limit.** set by
37bc0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d [sqlite3_limit]
37bd0 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 ([SQLITE_LIMIT_F
37be0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 UNCTION_ARG]).
37bf0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 If the third.**
37c00 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 parameter is les
37c10 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 s than -1 or gre
37c20 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 ater than 127 th
37c30 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
37c40 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e is.** undefined.
37c50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 .**.** ^The four
37c60 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 th parameter, eT
37c70 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 extRep, specifie
37c80 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 s what.** [SQLIT
37c90 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e E_UTF8 | text en
37ca0 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c coding] this SQL
37cb0 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 function prefer
37cc0 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 s for.** its par
37cd0 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 ameters. The ap
37ce0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
37cf0 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 set this parame
37d00 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 ter to.** [SQLIT
37d10 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 E_UTF16LE] if th
37d20 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 e function imple
37d30 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 mentation invoke
37d40 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 s .** [sqlite3_v
37d50 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d alue_text16le()]
37d60 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 on an input, or
37d70 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 [SQLITE_UTF16BE
37d80 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c ] if the.** impl
37d90 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b ementation invok
37da0 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 es [sqlite3_valu
37db0 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e e_text16be()] on
37dc0 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a an input, or.**
37dd0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 [SQLITE_UTF16]
37de0 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 if [sqlite3_valu
37df0 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 e_text16()] is u
37e00 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f sed, or [SQLITE_
37e10 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 UTF8].** otherwi
37e20 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 se. ^The same S
37e30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 QL function may
37e40 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 be registered mu
37e50 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 ltiple times usi
37e60 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 ng.** different
37e70 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 preferred text e
37e80 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 ncodings, with d
37e90 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 ifferent impleme
37ea0 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 ntations for.**
37eb0 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a each encoding..*
37ec0 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 * ^When multiple
37ed0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
37ee0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e of the same fun
37ef0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 ction are availa
37f00 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 ble, SQLite.** w
37f10 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 ill pick the one
37f20 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 that involves t
37f30 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 he least amount
37f40 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 of data conversi
37f50 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 on..**.** ^The f
37f60 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
37f70 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 may optionally b
37f80 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c e ORed with [SQL
37f90 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 ITE_DETERMINISTI
37fa0 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 C].** to signal
37fb0 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f that the functio
37fc0 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 n will always re
37fd0 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 turn the same re
37fe0 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 sult given.** th
37ff0 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 e same inputs wi
38000 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 thin a single SQ
38010 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f L statement. Mo
38020 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 st SQL functions
38030 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e are.** determin
38040 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c istic. The buil
38050 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 t-in [random()]
38060 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 SQL function is
38070 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a an example of a.
38080 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 ** function that
38090 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e is not determin
380a0 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 istic. The SQLi
380b0 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 te query planner
380c0 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 is able to.** p
380d0 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 erform additiona
380e0 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 l optimizations
380f0 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 on deterministic
38100 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 functions, so u
38110 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 se.** of the [SQ
38120 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 LITE_DETERMINIST
38130 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f IC] flag is reco
38140 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f mmended where po
38150 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ssible..**.** ^(
38160 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 The fifth parame
38170 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 ter is an arbitr
38180 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 ary pointer. Th
38190 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
381a0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 of the.** funct
381b0 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 ion can gain acc
381c0 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e ess to this poin
381d0 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ter using [sqlit
381e0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e e3_user_data()].
381f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 )^.**.** ^The si
38200 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 xth, seventh and
38210 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 eighth paramete
38220 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 rs, xFunc, xStep
38230 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 and xFinal, are
38240 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 .** pointers to
38250 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 C-language funct
38260 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d ions that implem
38270 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 ent the SQL func
38280 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
38290 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 gate. ^A scalar
382a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 SQL function req
382b0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 uires an impleme
382c0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 ntation of the x
382d0 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b Func.** callback
382e0 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e only; NULL poin
382f0 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 ters must be pas
38300 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 sed as the xStep
38310 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 and xFinal.** p
38320 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 arameters. ^An a
38330 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e ggregate SQL fun
38340 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 ction requires a
38350 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
38360 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 of xStep.** and
38370 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c xFinal and NULL
38380 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 pointer must be
38390 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e passed for xFun
383a0 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e c. ^To delete an
383b0 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c existing.** SQL
383c0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 function or agg
383d0 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c regate, pass NUL
383e0 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 L pointers for a
383f0 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f ll three functio
38400 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a n.** callbacks..
38410 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e **.** ^(If the n
38420 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 inth parameter t
38430 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 o sqlite3_create
38440 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 _function_v2() i
38450 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 s not NULL,.** t
38460 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 hen it is destru
38470 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 ctor for the app
38480 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f lication data po
38490 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 inter. .** The d
384a0 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 estructor is inv
384b0 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 oked when the fu
384c0 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 nction is delete
384d0 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 d, either by bei
384e0 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 ng.** overloaded
384f0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 or when the dat
38500 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
38510 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 closes.)^.** ^T
38520 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 he destructor is
38530 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 also invoked if
38540 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 the call to.**
38550 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
38560 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 unction_v2() fai
38570 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 ls..** ^When the
38580 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c destructor call
38590 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 back of the tent
385a0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 h parameter is i
385b0 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 nvoked, it.** is
385c0 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 passed a single
385d0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
385e0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
385f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
38600 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 a .** pointer wh
38610 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 ich was the fift
38620 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
38630 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
38640 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a nction_v2()..**.
38650 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 ** ^It is permit
38660 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 ted to register
38670 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 multiple impleme
38680 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ntations of the
38690 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e same.** function
386a0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 s with the same
386b0 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 name but with ei
386c0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e ther differing n
386d0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 umbers of.** arg
386e0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 uments or differ
386f0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 ing preferred te
38700 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e xt encodings. ^
38710 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a SQLite will use.
38720 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 ** the implement
38730 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 ation that most
38740 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 closely matches
38750 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 the way in which
38760 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 the.** SQL func
38770 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e tion is used. ^
38780 41 20 66 75 6e