0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35 /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 urce code. In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 al notice, here
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 *.** May you
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 do good and not
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 evil..** May
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65 you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 hers..** May
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79 you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76 ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66 ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20 ile defines the
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74 interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73 client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69 . If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64 on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69 onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41 ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73 PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64 tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63 not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74 ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68 e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66 at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61 ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74 s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74 al". Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 ite. We do not
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67 anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65 but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 inor changes.**
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63 ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 e is derived.**
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 this file. Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66 e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 file makes some
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68 this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73 ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64 art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23 ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48 define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72 .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64 g.h> /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74 ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 */../*.** Make
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 C++..*/.#ifdef
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65 __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20 ../*.** Provide
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20 verride linkage
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20 features of the
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69 interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54 fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72 ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65 QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43 fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54 ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53 DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51 QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65 TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50 def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72 nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20 faces as either
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78 deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 perimental. New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 should not use
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72 deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65 faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 atibility only.
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61 ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74 aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69 d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67 ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61 that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 nd gone back to
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 using simple.**
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 le-Time Library
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70 ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61 .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69 luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 ng literal that
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 rsion in the.**
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77 format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61 here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72 er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64 .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 Y is the minor
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65 nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 cro resolves to
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69 an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59 + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20 , and Z are the
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 same.** numbers
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79 N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20 so.** be larger
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65 than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69 from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68 s derived. Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 er Y will.** be
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20 emented or else
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20 ill be reset to
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65 18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73 source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 been stored in
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 ystem</a>. ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65 D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65 which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20 e.** within its
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 ate and time of
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73 or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 h of the entire
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66 source tree. If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65 the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69 has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73 ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74 ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65 checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73 igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65 h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 LITE_VERSION
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d OURCE_ID "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 un-Time Library
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 TE_SOURCE_ID] C
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f file. ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 s might include
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 atch the macros
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72 , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 ing library and
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65 ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30 ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 ins the text of
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 .** macro. ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ant. The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 tring constants
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 within the DLL.
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c BER]. ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 ite3_sourceid()
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 ant whose value
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20 rocessor macro.
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74 Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73 e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67 py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74 amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61 he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68 racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20 e hash might be
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61 void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 on returns 0 or
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 compile time.
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 ed from the .**
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 (). .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 ined at compile
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e n string. ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 pointer. ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 tion at compile
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 time..**.** See
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69 pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66 returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 and only if.**
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74 tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e t mutexes. When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72 THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 threadsafe. Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 itted. Without
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 the mutexes, it
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 rs a measurable
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 importance, it
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 texes. But for
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 maximum safety,
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61 ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 rsion of SQLite
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 interface only
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 x setting.** of
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 ADSAFE] flag. I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 xes are enabled
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61 r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 nfig()].** with
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54 the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65 IZED]. ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 ead safety, not
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 ting made by.**
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 threadsafe().**
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 is unchanged by
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 le.** KEYWORDS:
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 tion} {database
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20 ite database is
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 3". It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69 lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20 ts destructors.
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 There are many
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 ces (such as.**
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65 three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 ss-platform way
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 es typedefs for
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 sqlite3_uint64
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 te_uint64 types
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 lite3_int64 and
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 36854775808 and
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 5807 inclusive.
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 te_uint64 types
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35 6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 64_TYPE. typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45 ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20 _UINT64_TYPE.
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73 te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20 e . typedef
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69 e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 _). typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 4;. typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e se. typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 # define double
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 3REF: Closing A
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75 3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75 tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65 ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 t..** ^Calls to
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 sqlite3_close()
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53 e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 QLITE_OK] if.**
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66 ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61 ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61 d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 n is associated
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65 ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20 ).** will leave
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 is called with
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 eallocated when
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 ished. The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72 ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 bage collected,
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 der in which.**
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 destructors are
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 B handles], and
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 s associated.**
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 3] object prior
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 t. ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61 n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 p] objects then
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64 TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 andles],.** and
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 stroyed while a
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 atically rolled
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 back..**.** The
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 ust be either a
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 NULL.** pointer
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 or an [sqlite3]
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 btained.** from
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 d deprecated. I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 r historical.**
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ted..*/.typedef
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 apper around.**
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 e statements of
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 ce runs zero or
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 atements passed
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 context of the
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 tion] passed in
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 gument. ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 is invoked for
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 QL statements.
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e k invocation. ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 e3_exec().** is
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 re skipped. ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 3_free()].** on
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73 arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 ssage string is
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 not NULL and no
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 ng the callback
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 subsequent SQL
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 esult. ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d mn. ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 nter for the.**
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 L pointer. ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 exec() callback
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 rictions:.**.**
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 e 1st parameter
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 ).** is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 t not close the
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 tion] specified
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 by.** the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 modify the SQL
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 assed into.**
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a exec(. sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 tabase */. cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 t char *sql,
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 . int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a r**,char**), /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 on */. void *,
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 /. char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 g
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 Result Codes.**
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 QLite functions
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 SQLITE_OK
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 0 /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 RROR 1
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72 /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 TE_INTERNAL
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 2 /* Internal
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 SQLITE_PERM
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 3 /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nied */.#define
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 SQLITE_ABORT
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 4 /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 _BUSY 5
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 TE_LOCKED
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6 /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 7 /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 TE_READONLY
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 8 /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f TERRUPT 9 /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 OERR 10
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 /* Some kind of
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 T 11 /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 e database disk
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 LITE_NOTFOUND
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 12 /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 ITE_FULL
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 13 /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 ITE_CANTOPEN
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 14 /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 COL 15 /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f PTY 16 /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 QLITE_SCHEMA
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 17 /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 SQLITE_TOOBIG
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 18 /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 CONSTRAINT 19
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 _MISUSE 21
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 NOLFS 22
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a H 23 /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 SQLITE_FORMAT
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20 24 /* Not
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 used */.#define
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 SQLITE_RANGE
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 25 /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 te3_bind out of
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 SQLITE_NOTADB
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 26 /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 opened that is
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 QLITE_NOTICE
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 27 /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a NING 28 /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 OW 100
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 ne SQLITE_DONE
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 101 /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 tions}.**.** In
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 eturn one of 30
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 lt codes]. Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 ver, experience
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 any of.** these
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f ned. They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 t provide as.**
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 about problems
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 ight like. In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33 .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72 .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 ()] API. Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 e extended code
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 for.** the most
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 )]..*/.#define S
5170: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53 QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53 ING_COLLSEQ (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31 QLITE_ERROR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
51b0: 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59 LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c LITE_ERROR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
51f0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 ITE_IOERR_READ
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c ITE_IOERR | (1<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
5240: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 EAD (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 TE_IOERR | (2<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 E_IOERR_WRITE
5280: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 E_IOERR | (3<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 _IOERR_FSYNC
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 _IOERR | (4<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
52f0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 IOERR_DIR_FSYNC
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a IOERR | (5<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5330: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 OERR_TRUNCATE
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 OERR | (6<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5370: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 ERR_FSTAT
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5390: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 ERR | (7<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
53b0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 RR_UNLOCK
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
53d0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 RR | (8<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
53f0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 R_RDLOCK
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
5410: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 R | (9<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5430: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5450: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 | (10<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5470: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 _BLOCKED
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5490: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 | (11<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
54b0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 _NOMEM
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
54d0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 | (12<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
54f0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 _ACCESS
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5510: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 | (13<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5530: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f _CHECKRESERVEDLO
5540: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 CK (SQLITE_IOERR
5550: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 | (14<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5570: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 _LOCK
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5590: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 | (15<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
55b0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 _CLOSE
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
55d0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 | (16<<8)).#def
55e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
55f0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 _DIR_CLOSE
5600: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5610: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 | (17<<8)).#def
5620: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5630: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 _SHMOPEN
5640: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5650: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 | (18<<8)).#def
5660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5670: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 _SHMSIZE
5680: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5690: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 | (19<<8)).#def
56a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
56b0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 _SHMLOCK
56c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
56d0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 | (20<<8)).#def
56e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
56f0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 _SHMMAP
5700: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5710: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 | (21<<8)).#def
5720: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5730: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 _SEEK
5740: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5750: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 | (22<<8)).#def
5760: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5770: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 _DELETE_NOENT
5780: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5790: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 | (23<<8)).#def
57a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
57b0: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 _MMAP
57c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
57d0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 | (24<<8)).#def
57e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
57f0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 _GETTEMPPATH
5800: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5810: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 | (25<<8)).#def
5820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5830: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 _CONVPATH
5840: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5850: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 | (26<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5870: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20 _VNODE
5880: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5890: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 | (27<<8)).#def
58a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
58b0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20 _AUTH
58c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
58d0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66 | (28<<8)).#def
58e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
58f0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20 _BEGIN_ATOMIC
5900: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5910: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66 | (29<<8)).#def
5920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5930: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20 _COMMIT_ATOMIC
5940: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5950: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66 | (30<<8)).#def
5960: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5970: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 _ROLLBACK_ATOMIC
5980: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5990: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66 | (31<<8)).#def
59a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 ine SQLITE_LOCKE
59b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 D_SHAREDCACHE
59c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 (SQLITE_LOCKE
59d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 D | (1<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 fine SQLITE_BUSY
59f0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 _RECOVERY
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 (SQLITE_BUSY
5a10: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 | (1<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
5a30: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 Y_SNAPSHOT
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 (SQLITE_BUS
5a50: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 Y | (2<<8)).#
5a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
5a70: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 NTOPEN_NOTEMPDIR
5a80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 (SQLITE_CA
5a90: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 NTOPEN | (1<<8))
5aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5ab0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 CANTOPEN_ISDIR
5ac0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5ad0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 CANTOPEN | (2<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5af0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 E_CANTOPEN_FULLP
5b00: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 ATH (SQLIT
5b10: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c E_CANTOPEN | (3<
5b20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5b30: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e ITE_CANTOPEN_CON
5b40: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c VPATH (SQL
5b50: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 ITE_CANTOPEN | (
5b60: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 4<<8)).#define S
5b70: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 QLITE_CORRUPT_VT
5b80: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 AB (S
5b90: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 QLITE_CORRUPT |
5ba0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
5bb0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f SQLITE_READONLY_
5bc0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 RECOVERY (
5bd0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 SQLITE_READONLY
5be0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
5bf0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
5c00: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 Y_CANTLOCK
5c10: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c (SQLITE_READONL
5c20: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 Y | (2<<8)).#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f ine SQLITE_READO
5c40: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 NLY_ROLLBACK
5c50: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f (SQLITE_READO
5c60: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 NLY | (3<<8)).#d
5c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
5c80: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 DONLY_DBMOVED
5c90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 (SQLITE_REA
5ca0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a DONLY | (4<<8)).
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
5cc0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e 49 54 EADONLY_CANTINIT
5cd0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 (SQLITE_R
5ce0: 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c 38 29 EADONLY | (5<<8)
5cf0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5d00: 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45 43 54 _READONLY_DIRECT
5d10: 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49 54 45 ORY (SQLITE
5d20: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36 3c 3c _READONLY | (6<<
5d30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5d40: 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 TE_ABORT_ROLLBAC
5d50: 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 K (SQLI
5d60: 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 TE_ABORT | (2<<8
5d70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5d80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 E_CONSTRAINT_CHE
5d90: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 CK (SQLIT
5da0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
5db0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
5dc0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5dd0: 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 _COMMITHOOK (S
5de0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5df0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
5e00: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
5e10: 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 AINT_FOREIGNKEY
5e20: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
5e30: 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 AINT | (3<<8)).#
5e40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
5e50: 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f NSTRAINT_FUNCTIO
5e60: 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f N (SQLITE_CO
5e70: 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 NSTRAINT | (4<<8
5e80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5e90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 E_CONSTRAINT_NOT
5ea0: 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 NULL (SQLIT
5eb0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
5ec0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 5<<8)).#define S
5ed0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5ee0: 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 _PRIMARYKEY (S
5ef0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5f00: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 | (6<<8)).#defi
5f10: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
5f20: 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 AINT_TRIGGER
5f30: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
5f40: 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 AINT | (7<<8)).#
5f50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
5f60: 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 NSTRAINT_UNIQUE
5f70: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
5f80: 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 NSTRAINT | (8<<8
5f90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5fa0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 E_CONSTRAINT_VTA
5fb0: 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 B (SQLIT
5fc0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
5fd0: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 9<<8)).#define S
5fe0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5ff0: 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 _ROWID (S
6000: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
6010: 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 |(10<<8)).#defi
6020: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 ne SQLITE_NOTICE
6030: 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 _RECOVER_WAL
6040: 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 (SQLITE_NOTICE
6050: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
6060: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 ne SQLITE_NOTICE
6070: 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 _RECOVER_ROLLBAC
6080: 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 K (SQLITE_NOTICE
6090: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
60a0: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e ne SQLITE_WARNIN
60b0: 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 G_AUTOINDEX
60c0: 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e (SQLITE_WARNIN
60d0: 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 G | (1<<8)).#def
60e0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f ine SQLITE_AUTH_
60f0: 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20 USER
6100: 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 (SQLITE_AUTH
6110: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
6120: 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 e SQLITE_OK_LOAD
6130: 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20 _PERMANENTLY
6140: 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 (SQLITE_OK | (1
6150: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 <<8))../*.** CAP
6160: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 I3REF: Flags For
6170: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 File Open Opera
6180: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tions.**.** Thes
6190: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 e bit values are
61a0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
61b0: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 e in the.** 3rd
61c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
61d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
61e0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 2()] interface a
61f0: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 nd.** in the 4th
6200: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
6210: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
6220: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f Open] method..*/
6230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6240: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 OPEN_READONLY
6250: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
6260: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
6270: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
6280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6290: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 OPEN_READWRITE
62a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
62b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
62c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
62d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
62e0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 OPEN_CREATE
62f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
6300: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
6310: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
6320: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6330: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
6340: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 SE 0x00000008
6350: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6370: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 OPEN_EXCLUSIVE
6380: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
6390: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
63a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
63b0: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 OPEN_AUTOPROXY
63c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0x00000020
63d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
63e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
63f0: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 OPEN_URI
6400: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0x00000040
6410: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
6420: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
6430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6440: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 OPEN_MEMORY
6450: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0x00000080
6460: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
6470: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
6480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6490: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 OPEN_MAIN_DB
64a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0x00000100
64b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
64c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
64d0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 OPEN_TEMP_DB
64e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0x00000200
64f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6510: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 OPEN_TRANSIENT_D
6520: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 B 0x00000400
6530: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6550: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
6560: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 L 0x00000800
6570: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6590: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
65a0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 L 0x00001000
65b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
65c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
65d0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 OPEN_SUBJOURNAL
65e0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0x00002000
65f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6600: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6610: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
6620: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 NAL 0x00004000
6630: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6650: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 OPEN_NOMUTEX
6660: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 0x00008000
6670: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
6680: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
6690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
66a0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 OPEN_FULLMUTEX
66b0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 0x00010000
66c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
66d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
66e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
66f0: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
6700: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 0x00020000
6710: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
6720: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
6730: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6740: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
6750: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 E 0x00040000
6760: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
6770: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
6780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6790: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 OPEN_WAL
67a0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 0x00080000
67b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
67c0: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 ../* Reserved:
67d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
67e0: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 0x00F0000
67f0: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 0 */../*.** CAPI
6800: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 3REF: Device Cha
6810: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a racteristics.**.
6820: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 ** The xDeviceCh
6830: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 aracteristics me
6840: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c thod of the [sql
6850: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
6860: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 .** object retur
6870: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 ns an integer wh
6880: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 ich is a vector
6890: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 of these.** bit
68a0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e values expressin
68b0: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 g I/O characteri
68c0: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 stics of the mas
68d0: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 s storage.** dev
68e0: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 ice that holds t
68f0: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 he file that the
6900: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
6910: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 hods].** refers
6920: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 to..**.** The SQ
6930: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6940: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 C property means
6950: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 that all writes
6960: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 of.** any size
6970: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
6980: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6990: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a OMICnnn values.*
69a0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 * mean that writ
69b0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 es of blocks tha
69c0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 t are nnn bytes
69d0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 in size and.** a
69e0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e re aligned to an
69f0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 address which i
6a00: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c s an integer mul
6a10: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 tiple of.** nnn
6a20: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
6a30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
6a40: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 FE_APPEND value
6a50: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 means.** that wh
6a60: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e en data is appen
6a70: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 ded to a file, t
6a80: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e he data is appen
6a90: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 ded.** first the
6aa0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 n the size of th
6ab0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 e file is extend
6ac0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 ed, never the ot
6ad0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e her.** way aroun
6ae0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 d. The SQLITE_I
6af0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
6b00: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
6b10: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 hat.** informati
6b20: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f on is written to
6b30: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d disk in the sam
6b40: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 e order as calls
6b50: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e .** to xWrite().
6b60: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
6b70: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 AP_POWERSAFE_OVE
6b80: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 RWRITE property
6b90: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 means that.** af
6ba0: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f ter reboot follo
6bb0: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 wing a crash or
6bc0: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 power loss, the
6bd0: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a only bytes in a.
6be0: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 ** file that wer
6bf0: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 e written at the
6c00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 application lev
6c10: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 el might have ch
6c20: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 anged.** and tha
6c30: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 t adjacent bytes
6c40: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 , even bytes wit
6c50: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 hin the same sec
6c60: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 tor are.** guara
6c70: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 nteed to be unch
6c80: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 anged. The SQLI
6c90: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 TE_IOCAP_UNDELET
6ca0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a ABLE_WHEN_OPEN.*
6cb0: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 * flag indicates
6cc0: 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e that a file can
6cd0: 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 not be deleted w
6ce0: 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a hen open. The.*
6cf0: 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 * SQLITE_IOCAP_I
6d00: 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e MMUTABLE flag in
6d10: 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 dicates that the
6d20: 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 file is on.** r
6d30: 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 ead-only media a
6d40: 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 nd cannot be cha
6d50: 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f nged even by pro
6d60: 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 cesses with.** e
6d70: 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 levated privileg
6d80: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 es..**.** The SQ
6d90: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 LITE_IOCAP_BATCH
6da0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
6db0: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
6dc0: 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 66 69 underlying.** fi
6dd0: 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74 lesystem support
6de0: 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70 6c 65 s doing multiple
6df0: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e write operation
6e00: 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77 68 65 s atomically whe
6e10: 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69 74 65 n those.** write
6e20: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 operations are
6e30: 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b 53 51 bracketed by [SQ
6e40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e LITE_FCNTL_BEGIN
6e50: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 61 _ATOMIC_WRITE] a
6e60: 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 nd.** [SQLITE_FC
6e70: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 NTL_COMMIT_ATOMI
6e80: 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23 64 65 C_WRITE]..*/.#de
6e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6ea0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 P_ATOMIC
6eb0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6ec0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 001.#define SQLI
6ed0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 TE_IOCAP_ATOMIC5
6ee0: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 12
6ef0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 0x00000002.#defi
6f00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6f10: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 ATOMIC1K
6f20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
6f30: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
6f40: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 _IOCAP_ATOMIC2K
6f50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
6f60: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 00000008.#define
6f70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6f80: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 OMIC4K
6f90: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 0x00000010.
6fa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6fb0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 OCAP_ATOMIC8K
6fc0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
6fd0: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 000020.#define S
6fe0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
6ff0: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 IC16K
7000: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 0x00000040.#d
7010: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
7020: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 AP_ATOMIC32K
7030: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
7040: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0080.#define SQL
7050: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
7060: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 64K
7070: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 0x00000100.#def
7080: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
7090: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 _SAFE_APPEND
70a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 0x000002
70b0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
70c0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
70d0: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 AL 0
70e0: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e x00000400.#defin
70f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 e SQLITE_IOCAP_U
7100: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f NDELETABLE_WHEN_
7110: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 OPEN 0x00000800
7120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7130: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f IOCAP_POWERSAFE_
7140: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 OVERWRITE 0x0
7150: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 0001000.#define
7160: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d SQLITE_IOCAP_IMM
7170: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 UTABLE
7180: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 0x00002000.#
7190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
71a0: 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 CAP_BATCH_ATOMIC
71b0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
71c0: 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 04000../*.** CAP
71d0: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b I3REF: File Lock
71e0: 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a ing Levels.**.**
71f0: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 SQLite uses one
7200: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 of these intege
7210: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 r values as the
7220: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 second.** argume
7230: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d nt to calls it m
7240: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 akes to the xLoc
7250: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 k() and xUnlock(
7260: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 ) methods.** of
7270: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d an [sqlite3_io_m
7280: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a ethods] object..
7290: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
72a0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 E_LOCK_NONE
72b0: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 0.#define S
72c0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
72d0: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 D 1.#defi
72e0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 ne SQLITE_LOCK_R
72f0: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 ESERVED 2.#
7300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
7310: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 CK_PENDING
7320: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 3.#define SQLIT
7330: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 E_LOCK_EXCLUSIVE
7340: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 4../*.** CA
7350: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e PI3REF: Synchron
7360: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 ization Type Fla
7370: 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 gs.**.** When SQ
7380: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 Lite invokes the
7390: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 xSync() method
73a0: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 of an.** [sqlite
73b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
73c0: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 ject it uses a c
73d0: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a ombination of.**
73e0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 these integer v
73f0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 alues as the sec
7400: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a ond argument..**
7410: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c .** When the SQL
7420: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c ITE_SYNC_DATAONL
7430: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 Y flag is used,
7440: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 it means that th
7450: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 e.** sync operat
7460: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 ion only needs t
7470: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 o flush data to
7480: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 mass storage. I
7490: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 node.** informat
74a0: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 ion need not be
74b0: 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 flushed. If the
74c0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 lower four bits
74d0: 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 of the flag.** e
74e0: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 qual SQLITE_SYNC
74f0: 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 _NORMAL, that me
7500: 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 ans to use norma
7510: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 l fsync() semant
7520: 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c ics..** If the l
7530: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 ower four bits e
7540: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 qual SQLITE_SYNC
7550: 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e _FULL, that mean
7560: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 s.** to use Mac
7570: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 OS X style fulls
7580: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 ync instead of f
7590: 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f sync()..**.** Do
75a0: 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 not confuse the
75b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 SQLITE_SYNC_NOR
75c0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 MAL and SQLITE_S
75d0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a YNC_FULL flags.*
75e0: 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 * with the [PRAG
75f0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d MA synchronous]=
7600: 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 NORMAL and [PRAG
7610: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d MA synchronous]=
7620: 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 FULL.** settings
7630: 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e . The [synchron
7640: 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 ous pragma] dete
7650: 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c rmines when call
7660: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e s to the.** xSyn
7670: 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 c VFS method occ
7680: 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 ur and applies u
7690: 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 niformly across
76a0: 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a all platforms..*
76b0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e * The SQLITE_SYN
76c0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c C_NORMAL and SQL
76d0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c ITE_SYNC_FULL fl
76e0: 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f ags determine ho
76f0: 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f w.** energetic o
7700: 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f r rigorous or fo
7710: 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 rceful the sync
7720: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 operations are a
7730: 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 nd.** only make
7740: 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 a difference on
7750: 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 Mac OSX for the
7760: 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 default SQLite c
7770: 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 ode..** (Third-p
7780: 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 arty VFS impleme
7790: 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 ntations might a
77a0: 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 lso make the dis
77b0: 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 tinction.** betw
77c0: 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f een SQLITE_SYNC_
77d0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 NORMAL and SQLIT
77e0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 E_SYNC_FULL, but
77f0: 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 among the.** op
7800: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 erating systems
7810: 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 natively support
7820: 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e ed by SQLite, on
7830: 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 ly Mac OSX.** ca
7840: 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 res about the di
7850: 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 fference.).*/.#d
7860: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e efine SQLITE_SYN
7870: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 C_NORMAL
7880: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 0x00002.#define
7890: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
78a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
78b0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
78c0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 _SYNC_DATAONLY
78d0: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 0x00010../*.
78e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
78f0: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 Interface Open F
7900: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a ile Handle.**.**
7910: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c An [sqlite3_fil
7920: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 e] object repres
7930: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c ents an open fil
7940: 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 e in the .** [sq
7950: 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 lite3_vfs | OS i
7960: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e nterface layer].
7970: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 Individual OS
7980: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 interface.** imp
7990: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c lementations wil
79a0: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 l.** want to sub
79b0: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 class this objec
79c0: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 t by appending a
79d0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
79e0: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 .** for their ow
79f0: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 n use. The pMet
7a00: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 hods entry is a
7a10: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
7a20: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
7a30: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 hods] object tha
7a40: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 t defines method
7a50: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 s for performing
7a60: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f .** I/O operatio
7a70: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 ns on the open f
7a80: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ile..*/.typedef
7a90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 struct sqlite3_f
7aa0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 ile sqlite3_file
7ab0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
7ac0: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 _file {. const
7ad0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
7ae0: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 o_methods *pMeth
7af0: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 ods; /* Methods
7b00: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c for an open fil
7b10: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e */.};../*.** C
7b20: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 API3REF: OS Inte
7b30: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 rface File Virtu
7b40: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 al Methods Objec
7b50: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 t.**.** Every fi
7b60: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 le opened by the
7b70: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f [sqlite3_vfs.xO
7b80: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 pen] method popu
7b90: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c lates an.** [sql
7ba0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
7bb0: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d t (or, more comm
7bc0: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 only, a subclass
7bd0: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
7be0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
7bf0: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 ) with a pointer
7c00: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
7c10: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a of this object..
7c20: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 ** This object d
7c30: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f efines the metho
7c40: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f ds used to perfo
7c50: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 rm various opera
7c60: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 tions.** against
7c70: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 the open file r
7c80: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 epresented by th
7c90: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d e [sqlite3_file]
7ca0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 object..**.** I
7cb0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 f the [sqlite3_v
7cc0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 fs.xOpen] method
7cd0: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 sets the sqlite
7ce0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 3_file.pMethods
7cf0: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 element .** to a
7d00: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 non-NULL pointe
7d10: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 r, then the sqli
7d20: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 te3_io_methods.x
7d30: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 Close method.**
7d40: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 may be invoked e
7d50: 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 ven if the [sqli
7d60: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 te3_vfs.xOpen] r
7d70: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 eported that it
7d80: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 failed. The.**
7d90: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 only way to prev
7da0: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 ent a call to xC
7db0: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 lose following a
7dc0: 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 failed [sqlite3
7dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 _vfs.xOpen].** i
7de0: 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 s for the [sqlit
7df0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f e3_vfs.xOpen] to
7e00: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 set the sqlite3
7e10: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 _file.pMethods e
7e20: 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c lement.** to NUL
7e30: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 L..**.** The fla
7e40: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
7e50: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 Sync may be one
7e60: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f of [SQLITE_SYNC_
7e70: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 NORMAL] or.** [S
7e80: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d QLITE_SYNC_FULL]
7e90: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f . The first cho
7ea0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 ice is the norma
7eb0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 l fsync()..** Th
7ec0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 e second choice
7ed0: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 is a Mac OS X st
7ee0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 yle fullsync. T
7ef0: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f he [SQLITE_SYNC_
7f00: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 DATAONLY].** fla
7f10: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e g may be ORed in
7f20: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
7f30: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 t only the data
7f40: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 of the file.** a
7f50: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 nd not its inode
7f60: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e needs to be syn
7f70: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ced..**.** The i
7f80: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f nteger values to
7f90: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e xLock() and xUn
7fa0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f lock() are one o
7fb0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 f.** <ul>.** <li
7fc0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e > [SQLITE_LOCK_N
7fd0: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ONE],.** <li> [S
7fe0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
7ff0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
8000: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
8010: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
8020: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 ITE_LOCK_PENDING
8030: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ], or.** <li> [S
8040: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
8050: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a SIVE]..** </ul>.
8060: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 ** xLock() incre
8070: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 ases the lock. x
8080: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 Unlock() decreas
8090: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 es the lock..**
80a0: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 The xCheckReserv
80b0: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 edLock() method
80c0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 checks whether a
80d0: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ny database conn
80e0: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 ection,.** eithe
80f0: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 r in this proces
8100: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 s or in some oth
8110: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 er process, is h
8120: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 olding a RESERVE
8130: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f D,.** PENDING, o
8140: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b r EXCLUSIVE lock
8150: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 on the file. I
8160: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a t returns true.*
8170: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b * if such a lock
8180: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 exists and fals
8190: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a e otherwise..**.
81a0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 ** The xFileCont
81b0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 rol() method is
81c0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 a generic interf
81d0: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 ace that allows
81e0: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d custom.** VFS im
81f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f plementations to
8200: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f directly contro
8210: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 l an open file u
8220: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
8230: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
8240: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 l()] interface.
8250: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 The second "op"
8260: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a argument is an.
8270: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 ** integer opcod
8280: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 e. The third ar
8290: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 gument is a gene
82a0: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 ric pointer inte
82b0: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 nded to.** point
82c0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 to a structure
82d0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e that may contain
82e0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 arguments or sp
82f0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a ace in which to.
8300: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 ** write return
8310: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 values. Potenti
8320: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c al uses for xFil
8330: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 eControl() might
8340: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 be.** functions
8350: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b to enable block
8360: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 ing locks with t
8370: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e imeouts, to chan
8380: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e ge the.** lockin
8390: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 g strategy (for
83a0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 example to use d
83b0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 ot-file locks),
83c0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 to inquire.** ab
83d0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f out the status o
83e0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 f a lock, or to
83f0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b break stale lock
8400: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a s. The SQLite.*
8410: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 * core reserves
8420: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 all opcodes less
8430: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 than 100 for it
8440: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 s own use..** A
8450: 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 [file control op
8460: 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 codes | list of
8470: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 opcodes] less th
8480: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 an 100 is availa
8490: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 ble..** Applicat
84a0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 ions that define
84b0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 a custom xFileC
84c0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 ontrol method sh
84d0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 ould use opcodes
84e0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e .** greater than
84f0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 100 to avoid co
8500: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d nflicts. VFS im
8510: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 plementations sh
8520: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b ould.** return [
8530: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d SQLITE_NOTFOUND]
8540: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f for file contro
8550: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 l opcodes that t
8560: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 hey do not.** re
8570: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 cognize..**.** T
8580: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 he xSectorSize()
8590: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
85a0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 the sector size
85b0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 of the.** device
85c0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 that underlies
85d0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 the file. The s
85e0: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 ector size is th
85f0: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 e.** minimum wri
8600: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 te that can be p
8610: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 erformed without
8620: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f disturbing.** o
8630: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 ther bytes in th
8640: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 e file. The xDe
8650: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
8660: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 ics().** method
8670: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 returns a bit ve
8680: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 ctor describing
8690: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 behaviors of the
86a0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 .** underlying d
86b0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c evice:.**.** <ul
86c0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
86d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a E_IOCAP_ATOMIC].
86e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
86f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d IOCAP_ATOMIC512]
8700: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8710: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d _IOCAP_ATOMIC1K]
8720: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8730: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d _IOCAP_ATOMIC2K]
8740: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8750: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d _IOCAP_ATOMIC4K]
8760: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8770: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d _IOCAP_ATOMIC8K]
8780: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8790: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b _IOCAP_ATOMIC16K
87a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
87b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 E_IOCAP_ATOMIC32
87c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
87d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 TE_IOCAP_ATOMIC6
87e0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 4K].** <li> [SQL
87f0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
8800: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b PPEND].** <li> [
8810: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 SQLITE_IOCAP_SEQ
8820: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e UENTIAL].** <li>
8830: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 [SQLITE_IOCAP_U
8840: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f NDELETABLE_WHEN_
8850: 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 OPEN].** <li> [S
8860: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 QLITE_IOCAP_POWE
8870: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d RSAFE_OVERWRITE]
8880: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8890: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 _IOCAP_IMMUTABLE
88a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
88b0: 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 E_IOCAP_BATCH_AT
88c0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a OMIC].** </ul>.*
88d0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f *.** The SQLITE_
88e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f IOCAP_ATOMIC pro
88f0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
8900: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a all writes of.*
8910: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 * any size are a
8920: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
8930: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e TE_IOCAP_ATOMICn
8940: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 nn values.** mea
8950: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 n that writes of
8960: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 blocks that are
8970: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 nnn bytes in si
8980: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c ze and.** are al
8990: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 igned to an addr
89a0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 ess which is an
89b0: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 integer multiple
89c0: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 of.** nnn are a
89d0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
89e0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
89f0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 PEND value means
8a00: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 .** that when da
8a10: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 ta is appended t
8a20: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 o a file, the da
8a30: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a ta is appended.*
8a40: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 * first then the
8a50: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c size of the fil
8a60: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e e is extended, n
8a70: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a ever the other.*
8a80: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 * way around. T
8a90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
8aa0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 SEQUENTIAL prope
8ab0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a rty means that.*
8ac0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
8ad0: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b written to disk
8ae0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 in the same ord
8af0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 er as calls.** t
8b00: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a o xWrite()..**.*
8b10: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 * If xRead() ret
8b20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 urns SQLITE_IOER
8b30: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 R_SHORT_READ it
8b40: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a must also fill.*
8b50: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 * in the unread
8b60: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 portions of the
8b70: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f buffer with zero
8b80: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a s. A VFS that.*
8b90: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d * fails to zero-
8ba0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 fill short reads
8bb0: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 might seem to w
8bc0: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a ork. However,.*
8bd0: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 * failure to zer
8be0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 o-fill short rea
8bf0: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c ds will eventual
8c00: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 ly lead to.** da
8c10: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f tabase corruptio
8c20: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 n..*/.typedef st
8c30: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
8c40: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f methods sqlite3_
8c50: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 io_methods;.stru
8c60: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
8c70: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 thods {. int iV
8c80: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a ersion;. int (*
8c90: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f xClose)(sqlite3_
8ca0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
8cb0: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 xRead)(sqlite3_f
8cc0: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 ile*, void*, int
8cd0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 iAmt, sqlite3_i
8ce0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 nt64 iOfst);. i
8cf0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c nt (*xWrite)(sql
8d00: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 ite3_file*, cons
8d10: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d t void*, int iAm
8d20: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 t, sqlite3_int64
8d30: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 iOfst);. int (
8d40: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 *xTruncate)(sqli
8d50: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
8d60: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a e3_int64 size);.
8d70: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 int (*xSync)(s
8d80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
8d90: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 t flags);. int
8da0: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c (*xFileSize)(sql
8db0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 ite3_file*, sqli
8dc0: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 te3_int64 *pSize
8dd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b );. int (*xLock
8de0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
8df0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 int);. int (*x
8e00: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f Unlock)(sqlite3_
8e10: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 file*, int);. i
8e20: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 nt (*xCheckReser
8e30: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 vedLock)(sqlite3
8e40: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 _file*, int *pRe
8e50: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sOut);. int (*x
8e60: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c FileControl)(sql
8e70: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
8e80: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b op, void *pArg);
8e90: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 . int (*xSector
8ea0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 Size)(sqlite3_fi
8eb0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 le*);. int (*xD
8ec0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 eviceCharacteris
8ed0: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 tics)(sqlite3_fi
8ee0: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f le*);. /* Metho
8ef0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c ds above are val
8f00: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 id for version 1
8f10: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d */. int (*xShm
8f20: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c Map)(sqlite3_fil
8f30: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 e*, int iPg, int
8f40: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 pgsz, int, void
8f50: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 volatile**);.
8f60: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 int (*xShmLock)(
8f70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
8f80: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e nt offset, int n
8f90: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 , int flags);.
8fa0: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 void (*xShmBarri
8fb0: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 er)(sqlite3_file
8fc0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d *);. int (*xShm
8fd0: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 Unmap)(sqlite3_f
8fe0: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 ile*, int delete
8ff0: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 Flag);. /* Meth
9000: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 ods above are va
9010: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 lid for version
9020: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 2 */. int (*xFe
9030: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c tch)(sqlite3_fil
9040: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
9050: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 4 iOfst, int iAm
9060: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 t, void **pp);.
9070: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 int (*xUnfetch)
9080: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
9090: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f sqlite3_int64 iO
90a0: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 fst, void *p);.
90b0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 /* Methods abov
90c0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 e are valid for
90d0: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f version 3 */. /
90e0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 * Additional met
90f0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 hods may be adde
9100: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
9110: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a ases */.};../*.*
9120: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e * CAPI3REF: Stan
9130: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f dard File Contro
9140: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 l Opcodes.** KEY
9150: 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e WORDS: {file con
9160: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 trol opcodes} {f
9170: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f ile control opco
9180: 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 de}.**.** These
9190: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
91a0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f s are opcodes fo
91b0: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 r the xFileContr
91c0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 ol method.** of
91d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
91e0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
91f0: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c and for the [sql
9200: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
9210: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 l()].** interfac
9220: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a e..**.** <ul>.**
9230: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
9240: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a NTL_LOCKSTATE]].
9250: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
9260: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 CNTL_LOCKSTATE]
9270: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 opcode is used f
9280: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 or debugging. T
9290: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 his.** opcode ca
92a0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f uses the xFileCo
92b0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 ntrol method to
92c0: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e write the curren
92d0: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 t state of.** th
92e0: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b e lock (one of [
92f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
9300: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ], [SQLITE_LOCK_
9310: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c SHARED],.** [SQL
9320: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
9330: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b D], [SQLITE_LOCK
9340: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 _PENDING], or [S
9350: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
9360: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 SIVE]).** into a
9370: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 n integer that t
9380: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 he pArg argument
9390: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 points to. This
93a0: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 capability.** i
93b0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 s used during te
93c0: 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c sting and is onl
93d0: 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e y available when
93e0: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 the SQLITE_TEST
93f0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 .** compile-time
9400: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e option is used.
9410: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
9420: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 ITE_FCNTL_SIZE_H
9430: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 INT]].** The [SQ
9440: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f LITE_FCNTL_SIZE_
9450: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 HINT] opcode is
9460: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 used by SQLite t
9470: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a o give the VFS.*
9480: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f * layer a hint o
9490: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 f how large the
94a0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 database file wi
94b0: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 ll grow to be du
94c0: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 ring the.** curr
94d0: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e ent transaction.
94e0: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e This hint is n
94f0: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f ot guaranteed to
9500: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 be accurate but
9510: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 it.** is often
9520: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 close. The unde
9530: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 rlying VFS might
9540: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c choose to preal
9550: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a locate database.
9560: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 ** file space ba
9570: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 sed on this hint
9580: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c in order to hel
9590: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 p writes to the
95a0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 database.** file
95b0: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a run faster..**.
95c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
95d0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 FCNTL_CHUNK_SIZE
95e0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
95f0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 E_FCNTL_CHUNK_SI
9600: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 ZE] opcode is us
9610: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 ed to request th
9620: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 at the VFS.** ex
9630: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 tends and trunca
9640: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 tes the database
9650: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 file in chunks
9660: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 of a size specif
9670: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 ied.** by the us
9680: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 er. The fourth a
9690: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
96a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
96b0: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 ()] should .** p
96c0: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 oint to an integ
96d0: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f er (type int) co
96e0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 ntaining the new
96f0: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 chunk-size to u
9700: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f se.** for the no
9710: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 minated database
9720: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 . Allocating dat
9730: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 abase file space
9740: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 in large.** chu
9750: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 nks (say 1MB at
9760: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 a time), may red
9770: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 uce file-system
9780: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e fragmentation an
9790: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 d.** improve per
97a0: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 formance on some
97b0: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 systems..**.**
97c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
97d0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d TL_FILE_POINTER]
97e0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
97f0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e _FCNTL_FILE_POIN
9800: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 TER] opcode is u
9810: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 sed to obtain a
9820: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 pointer.** to th
9830: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d e [sqlite3_file]
9840: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 object associat
9850: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 ed with a partic
9860: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a ular database.**
9870: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 connection. Se
9880: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 e also [SQLITE_F
9890: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 CNTL_JOURNAL_POI
98a0: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 NTER]..**.** <li
98b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
98c0: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d JOURNAL_POINTER]
98d0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
98e0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 _FCNTL_JOURNAL_P
98f0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 OINTER] opcode i
9900: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e s used to obtain
9910: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
9920: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
9930: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 le] object assoc
9940: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a iated with the j
9950: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74 ournal file (eit
9960: 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c her.** the [roll
9970: 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 back journal] or
9980: 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61 the [write-ahea
9990: 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61 d log]) for a pa
99a0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 rticular databas
99b0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e e.** connection.
99c0: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 See also [SQLI
99d0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f TE_FCNTL_FILE_PO
99e0: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c INTER]..**.** <l
99f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
9a00: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a _SYNC_OMITTED]].
9a10: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 ** No longer in
9a20: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b use..**.** <li>[
9a30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 [SQLITE_FCNTL_SY
9a40: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c NC]].** The [SQL
9a50: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 ITE_FCNTL_SYNC]
9a60: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 opcode is genera
9a70: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 ted internally b
9a80: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 y SQLite and.**
9a90: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 sent to the VFS
9aa0: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f immediately befo
9ab0: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 re the xSync met
9ac0: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f hod is invoked o
9ad0: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 n a.** database
9ae0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e file descriptor.
9af0: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e Or, if the xSyn
9b00: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 c method is not
9b10: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 invoked .** beca
9b20: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 use the user has
9b30: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 configured SQLi
9b40: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 te with .** [PRA
9b50: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 GMA synchronous
9b60: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f | PRAGMA synchro
9b70: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 nous=OFF] it is
9b80: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 invoked in place
9b90: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e .** of the xSyn
9ba0: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 c method. In mos
9bb0: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 t cases, the poi
9bc0: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 nter argument pa
9bd0: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 ssed with.** thi
9be0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 s file-control i
9bf0: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c s NULL. However,
9c00: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 if the database
9c10: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 file is being s
9c20: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 ynced.** as part
9c30: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 of a multi-data
9c40: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 base commit, the
9c50: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 argument points
9c60: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e to a nul-termin
9c70: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 ated.** string c
9c80: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 ontaining the tr
9c90: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 ansactions maste
9ca0: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e r-journal file n
9cb0: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 ame. VFSes that
9cc0: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 .** do not need
9cd0: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 this signal shou
9ce0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f ld silently igno
9cf0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 re this opcode.
9d00: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a Applications .**
9d10: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c should not call
9d20: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
9d30: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 ontrol()] with t
9d40: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f his opcode as do
9d50: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 ing so may .** d
9d60: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 isrupt the opera
9d70: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 tion of the spec
9d80: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 ialized VFSes th
9d90: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 at do require it
9da0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b . .**.** <li>[[
9db0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d SQLITE_FCNTL_COM
9dc0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a MIT_PHASETWO]].*
9dd0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
9de0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 NTL_COMMIT_PHASE
9df0: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 TWO] opcode is g
9e00: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 enerated interna
9e10: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a lly by SQLite.**
9e20: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 and sent to the
9e30: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 VFS after a tra
9e40: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 nsaction has bee
9e50: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 n committed imme
9e60: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 diately.** but b
9e70: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 efore the databa
9e80: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 se is unlocked.
9e90: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f VFSes that do no
9ea0: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e t need this sign
9eb0: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c al.** should sil
9ec0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 ently ignore thi
9ed0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 s opcode. Applic
9ee0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f ations should no
9ef0: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 t call.** [sqlit
9f00: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
9f10: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 )] with this opc
9f20: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 ode as doing so
9f30: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 may disrupt the
9f40: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 .** operation of
9f50: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 the specialized
9f60: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 VFSes that do r
9f70: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a equire it. .**.
9f80: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
9f90: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 FCNTL_WIN32_AV_R
9fa0: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b ETRY]].** ^The [
9fb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
9fc0: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 32_AV_RETRY] opc
9fd0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 ode is used to c
9fe0: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 onfigure automat
9ff0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e ic.** retry coun
a000: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 ts and intervals
a010: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 for certain dis
a020: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 k I/O operations
a030: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 for the.** wind
a040: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 ows [VFS] in ord
a050: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f er to provide ro
a060: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 bustness in the
a070: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 presence of.** a
a080: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 nti-virus progra
a090: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c ms. By default,
a0a0: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 the windows VFS
a0b0: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 will retry file
a0c0: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 read,.** file w
a0d0: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 rite, and file d
a0e0: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 elete operations
a0f0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c up to 10 times,
a100: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a with a delay.**
a110: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f of 25 milliseco
a120: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 nds before the f
a130: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 irst retry and w
a140: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e ith the delay in
a150: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 creasing.** by a
a160: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 n additional 25
a170: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 milliseconds wit
a180: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e h each subsequen
a190: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a t retry. This.*
a1a0: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 * opcode allows
a1b0: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 these two values
a1c0: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 (10 retries and
a1d0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 25 milliseconds
a1e0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f of delay).** to
a1f0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 be adjusted. T
a200: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 he values are ch
a210: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 anged for all da
a220: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
a230: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 ns.** within the
a240: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 same process.
a250: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 The argument is
a260: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
a270: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 array of two.**
a280: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 integers where t
a290: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 he first integer
a2a0: 20 69 73 20 74 68 65 20 6e 65 77 20 72 65 74 72 is the new retr
a2b0: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 y count and the
a2c0: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 second.** intege
a2d0: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 r is the delay.
a2e0: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 If either integ
a2f0: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 er is negative,
a300: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 then the setting
a310: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 .** is not chang
a320: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 ed but instead t
a330: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f he prior value o
a340: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 f that setting i
a350: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 s written.** int
a360: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 o the array entr
a370: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 y, allowing the
a380: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 current retry se
a390: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 ttings to be.**
a3a0: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 interrogated. T
a3b0: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d he zDbName param
a3c0: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e eter is ignored.
a3d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
a3e0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 ITE_FCNTL_PERSIS
a3f0: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 T_WAL]].** ^The
a400: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 [SQLITE_FCNTL_PE
a410: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 RSIST_WAL] opcod
a420: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 e is used to set
a430: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a or query the.**
a440: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c persistent [WAL
a450: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c | Write Ahead L
a460: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 og] setting. By
a470: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 default, the au
a480: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 xiliary.** write
a490: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 ahead log and s
a4a0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c hared memory fil
a4b0: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e es used for tran
a4c0: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a saction control.
a4d0: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 ** are automatic
a4e0: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 ally deleted whe
a4f0: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e n the latest con
a500: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 nection to the d
a510: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 atabase.** close
a520: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 s. Setting pers
a530: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 istent WAL mode
a540: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c causes those fil
a550: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 es to persist af
a560: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 ter.** close. P
a570: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 ersisting the fi
a580: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 les is useful wh
a590: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 en other process
a5a0: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a es that do not.*
a5b0: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 * have write per
a5c0: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 mission on the d
a5d0: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e irectory contain
a5e0: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 ing the database
a5f0: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f file want.** to
a600: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 read the databa
a610: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 se file, as the
a620: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d WAL and shared m
a630: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 emory files must
a640: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 exist.** in ord
a650: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 er for the datab
a660: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 ase to be readab
a670: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 le. The fourth
a680: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
a690: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
a6a0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 ntrol()] for thi
a6b0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 s opcode should
a6c0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 be a pointer to
a6d0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 an integer..** T
a6e0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 hat integer is 0
a6f0: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 to disable pers
a700: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 istent WAL mode
a710: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 or 1 to enable p
a720: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c ersistent.** WAL
a730: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 mode. If the i
a740: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 nteger is -1, th
a750: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 en it is overwri
a760: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 tten with the cu
a770: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 rrent.** WAL per
a780: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 sistence setting
a790: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
a7a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 LITE_FCNTL_POWER
a7b0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d SAFE_OVERWRITE]]
a7c0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
a7d0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 _FCNTL_POWERSAFE
a7e0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f _OVERWRITE] opco
a7f0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 de is used to se
a800: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a t or query the.*
a810: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f * persistent "po
a820: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 wersafe-overwrit
a830: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 e" or "PSOW" set
a840: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 ting. The PSOW
a850: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 setting.** deter
a860: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 mines the [SQLIT
a870: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 E_IOCAP_POWERSAF
a880: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 E_OVERWRITE] bit
a890: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 of the.** xDevi
a8a0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 ceCharacteristic
a8b0: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 s methods. The f
a8c0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
a8d0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 to.** [sqlite3_f
a8e0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 ile_control()] f
a8f0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 or this opcode s
a900: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 hould be a point
a910: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 er to an integer
a920: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 ..** That intege
a930: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c r is 0 to disabl
a940: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f e zero-damage mo
a950: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c de or 1 to enabl
a960: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a e zero-damage.**
a970: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 mode. If the i
a980: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 nteger is -1, th
a990: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 en it is overwri
a9a0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 tten with the cu
a9b0: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 rrent.** zero-da
a9c0: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e mage mode settin
a9d0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 g..**.** <li>[[S
a9e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 QLITE_FCNTL_OVER
a9f0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 WRITE]].** ^The
aa00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 [SQLITE_FCNTL_OV
aa10: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 ERWRITE] opcode
aa20: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 is invoked by SQ
aa30: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 Lite after openi
aa40: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 ng.** a write tr
aa50: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 ansaction to ind
aa60: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 icate that, unle
aa70: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 ss it is rolled
aa80: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a back for some.**
aa90: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 reason, the ent
aaa0: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c ire database fil
aab0: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 e will be overwr
aac0: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 itten by the cur
aad0: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 rent .** transac
aae0: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 tion. This is us
aaf0: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 ed by VACUUM ope
ab00: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c rations..**.** <
ab10: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
ab20: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e L_VFSNAME]].** ^
ab30: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
ab40: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 L_VFSNAME] opcod
ab50: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
ab60: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 obtain the name
ab70: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 s of.** all [VFS
ab80: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 es] in the VFS s
ab90: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 tack. The names
aba0: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 are of all VFS
abb0: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a shims and the.**
abc0: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 final bottom-le
abd0: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 vel VFS are writ
abe0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 ten into memory
abf0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a obtained from .*
ac00: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f * [sqlite3_mallo
ac10: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 c()] and the res
ac20: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e ult is stored in
ac30: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 the char* varia
ac40: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 ble.** that the
ac50: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
ac60: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c of [sqlite3_fil
ac70: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 e_control()] poi
ac80: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 nts to..** The c
ac90: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 aller is respons
aca0: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 ible for freeing
acb0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e the memory when
acc0: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a done. As with.
acd0: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 ** all file-cont
ace0: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 rol actions, the
acf0: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 re is no guarant
ad00: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c ee that this wil
ad10: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f l actually.** do
ad20: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c anything. Call
ad30: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 ers should initi
ad40: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 alize the char*
ad50: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 variable to a NU
ad60: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e LL.** pointer in
ad70: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d case this file-
ad80: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 control is not i
ad90: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 mplemented. Thi
ada0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a s file-control.*
adb0: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f * is intended fo
adc0: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 r diagnostic use
add0: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 only..**.** <li
ade0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
adf0: 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a VFS_POINTER]].**
ae00: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^The [SQLITE_FC
ae10: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d NTL_VFS_POINTER]
ae20: 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 opcode finds a
ae30: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 pointer to the t
ae40: 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 op-level.** [VFS
ae50: 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e es] currently in
ae60: 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 use. ^(The arg
ae70: 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 ument X in.** sq
ae80: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
ae90: 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e ol(db,SQLITE_FCN
aea0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 TL_VFS_POINTER,X
aeb0: 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 ) must be.** of
aec0: 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 type "[sqlite3_v
aed0: 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f fs] **". This o
aee0: 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 pcodes will set
aef0: 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 *X.** to a point
af00: 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 er to the top-le
af10: 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 vel VFS.)^.** ^W
af20: 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 hen there are mu
af30: 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 ltiple VFS shims
af40: 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 in the stack, t
af50: 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 his opcode finds
af60: 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f the.** upper-mo
af70: 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a st shim only..**
af80: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
af90: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a _FCNTL_PRAGMA]].
afa0: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b ** ^Whenever a [
afb0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e PRAGMA] statemen
afc0: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 t is parsed, an
afd0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
afe0: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 AGMA] .** file c
aff0: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 ontrol is sent t
b000: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 o the open [sqli
b010: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
b020: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a corresponding.*
b030: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 * to the databas
b040: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 e file to which
b050: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 the pragma state
b060: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 ment refers. ^Th
b070: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f e argument.** to
b080: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e the [SQLITE_FCN
b090: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 TL_PRAGMA] file
b0a0: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 control is an ar
b0b0: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 ray of.** pointe
b0c0: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 rs to strings (c
b0d0: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 har**) in which
b0e0: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 the second eleme
b0f0: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a nt of the array.
b100: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ** is the name o
b110: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 f the pragma and
b120: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 the third eleme
b130: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 nt is the argume
b140: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 nt to the.** pra
b150: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 gma or NULL if t
b160: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f he pragma has no
b170: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 argument. ^The
b180: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a handler for an.
b190: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c ** [SQLITE_FCNTL
b1a0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
b1b0: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e ntrol can option
b1c0: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 ally make the fi
b1d0: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f rst element.** o
b1e0: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 f the char** arg
b1f0: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 ument point to a
b200: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 string obtained
b210: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
b220: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 printf()].** or
b230: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 the equivalent a
b240: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 nd that string w
b250: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 ill become the r
b260: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 esult of the pra
b270: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 gma or.** the er
b280: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 ror message if t
b290: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e he pragma fails.
b2a0: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c ^If the.** [SQL
b2b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
b2c0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 ] file control r
b2d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e eturns [SQLITE_N
b2e0: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e OTFOUND], then n
b2f0: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d ormal .** [PRAGM
b300: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f A] processing co
b310: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 ntinues. ^If th
b320: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
b330: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 PRAGMA].** file
b340: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 control returns
b350: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 [SQLITE_OK], the
b360: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 n the parser ass
b370: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a umes that the.**
b380: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 VFS has handled
b390: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 the PRAGMA itse
b3a0: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 lf and the parse
b3b0: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f r generates a no
b3c0: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 -op.** prepared
b3d0: 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 statement if res
b3e0: 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 ult string is NU
b3f0: 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 LL, or that retu
b400: 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 rns a copy.** of
b410: 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 the result stri
b420: 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 ng if the string
b430: 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a is non-NULL..**
b440: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 ^If the [SQLITE
b450: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 _FCNTL_PRAGMA] f
b460: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 ile control retu
b470: 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c rns.** any resul
b480: 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 t code other tha
b490: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 n [SQLITE_OK] or
b4a0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e [SQLITE_NOTFOUN
b4b0: 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a D], that means.*
b4c0: 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 * that the VFS e
b4d0: 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 ncountered an er
b4e0: 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 ror while handli
b4f0: 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 ng the [PRAGMA]
b500: 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 and the.** compi
b510: 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 lation of the PR
b520: 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 AGMA fails with
b530: 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 an error. ^The
b540: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
b550: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f AGMA].** file co
b560: 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 ntrol occurs at
b570: 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 the beginning of
b580: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e pragma statemen
b590: 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 t analysis and s
b5a0: 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 o.** it is able
b5b0: 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c to override buil
b5c0: 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 t-in [PRAGMA] st
b5d0: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
b5e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
b5f0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d TL_BUSYHANDLER]]
b600: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
b610: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c _FCNTL_BUSYHANDL
b620: 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 ER].** file-cont
b630: 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b rol may be invok
b640: 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 ed by SQLite on
b650: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
b660: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 e handle.** shor
b670: 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 tly after it is
b680: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 opened in order
b690: 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 to provide a cus
b6a0: 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 tom VFS with acc
b6b0: 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f ess.** to the co
b6c0: 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 nnections busy-h
b6d0: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e andler callback.
b6e0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 The argument is
b6f0: 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a of type (void *
b700: 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 *).** - an array
b710: 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 of two (void *)
b720: 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 values. The fir
b730: 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 st (void *) actu
b740: 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 ally points.** t
b750: 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 o a function of
b760: 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f type (int (*)(vo
b770: 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 id *)). In order
b780: 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 to invoke the c
b790: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 onnections.** bu
b7a0: 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 sy-handler, this
b7b0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 function should
b7c0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
b7d0: 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 the second (voi
b7e0: 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 d *) in.** the a
b7f0: 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 rray as the only
b800: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 argument. If it
b810: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
b820: 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 o, then the oper
b830: 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 ation.** should
b840: 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 be retried. If i
b850: 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 t returns zero,
b860: 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 the custom VFS s
b870: 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 hould abandon th
b880: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 e.** current ope
b890: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c ration..**.** <l
b8a0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
b8b0: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a _TEMPFILENAME]].
b8c0: 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 ** ^Application
b8d0: 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b can invoke the [
b8e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d SQLITE_FCNTL_TEM
b8f0: 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d PFILENAME] file-
b900: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 control.** to ha
b910: 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 ve SQLite genera
b920: 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 te a.** temporar
b930: 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 y filename using
b940: 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 the same algori
b950: 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c thm that is foll
b960: 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 owed to generate
b970: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 .** temporary fi
b980: 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 lenames for TEMP
b990: 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 tables and othe
b9a0: 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e r internal uses.
b9b0: 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e The.** argumen
b9c0: 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 t should be a ch
b9d0: 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 ar** which will
b9e0: 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 be filled with t
b9f0: 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 he filename.** w
ba00: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f ritten into memo
ba10: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ry obtained from
ba20: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
ba30: 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 ()]. The caller
ba40: 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b should.** invok
ba50: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 e [sqlite3_free(
ba60: 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 )] on the result
ba70: 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f to avoid a memo
ba80: 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c ry leak..**.** <
ba90: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
baa0: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a L_MMAP_SIZE]].**
bab0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
bac0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 TL_MMAP_SIZE] fi
bad0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 le control is us
bae0: 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 ed to query or s
baf0: 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 et the.** maximu
bb00: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 m number of byte
bb10: 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 s that will be u
bb20: 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d sed for memory-m
bb30: 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 apped I/O..** Th
bb40: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 e argument is a
bb50: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c pointer to a val
bb60: 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 ue of type sqlit
bb70: 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a e3_int64 that.**
bb80: 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 is an advisory
bb90: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
bba0: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 f bytes in the f
bbb0: 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 ile to memory ma
bbc0: 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 p. The.** point
bbd0: 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 er is overwritte
bbe0: 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 n with the old v
bbf0: 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 alue. The limit
bc00: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 is not changed
bc10: 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 if.** the value
bc20: 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 originally point
bc30: 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 ed to is negativ
bc40: 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 e, and so the cu
bc50: 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 rrent limit .**
bc60: 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 can be queried b
bc70: 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 y passing in a p
bc80: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 ointer to a nega
bc90: 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 tive number. Th
bca0: 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 is.** file-contr
bcb0: 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 ol is used inter
bcc0: 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 nally to impleme
bcd0: 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f nt [PRAGMA mmap_
bce0: 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 size]..**.** <li
bcf0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
bd00: 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b TRACE]].** The [
bd10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 SQLITE_FCNTL_TRA
bd20: 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c CE] file control
bd30: 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f provides adviso
bd40: 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a ry information.*
bd50: 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f * to the VFS abo
bd60: 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68 ut what the high
bd70: 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 er layers of the
bd80: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 SQLite stack ar
bd90: 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 e doing..** This
bda0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 file control is
bdb0: 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 used by some VF
bdc0: 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69 S activity traci
bdd0: 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 ng [shims]..** T
bde0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 he argument is a
bdf0: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
be00: 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 string. Higher
be10: 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a layers in the.*
be20: 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d * SQLite stack m
be30: 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 ay generate inst
be40: 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 ances of this fi
be50: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a le control if.**
be60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 the [SQLITE_USE
be70: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f _FCNTL_TRACE] co
be80: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
be90: 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a n is enabled..**
bea0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
beb0: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 _FCNTL_HAS_MOVED
bec0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
bed0: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 E_FCNTL_HAS_MOVE
bee0: 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 D] file control
bef0: 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 interprets its a
bf00: 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 rgument as a.**
bf10: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
bf20: 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 teger and it wri
bf30: 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e tes a boolean in
bf40: 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 to that integer
bf50: 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 depending.** on
bf60: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
bf70: 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e he file has been
bf80: 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c renamed, moved,
bf90: 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 or deleted sinc
bfa0: 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 e it.** was firs
bfb0: 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 t opened..**.**
bfc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
bfd0: 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e TL_WIN32_GET_HAN
bfe0: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 DLE]].** The [SQ
bff0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 LITE_FCNTL_WIN32
c000: 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 _GET_HANDLE] opc
c010: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ode can be used
c020: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a to obtain the.**
c030: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 underlying nati
c040: 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 ve file handle a
c050: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 ssociated with a
c060: 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 file handle. T
c070: 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 his file.** cont
c080: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 rol interprets i
c090: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 ts argument as a
c0a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 pointer to a na
c0b0: 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 tive file handle
c0c0: 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 and.** writes t
c0d0: 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c he resulting val
c0e0: 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 ue there..**.**
c0f0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
c100: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e TL_WIN32_SET_HAN
c110: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 DLE]].** The [SQ
c120: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 LITE_FCNTL_WIN32
c130: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 _SET_HANDLE] opc
c140: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 ode is used for
c150: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 debugging. This
c160: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 .** opcode cause
c170: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 s the xFileContr
c180: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 ol method to swa
c190: 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c p the file handl
c1a0: 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a e with the one.*
c1b0: 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 * pointed to by
c1c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e the pArg argumen
c1d0: 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c t. This capabil
c1e0: 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69 ity is used duri
c1f0: 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e ng testing.** an
c200: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 d only needs to
c210: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 be supported whe
c220: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 n SQLITE_TEST is
c230: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 defined..**.**
c240: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
c250: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a TL_WAL_BLOCK]].*
c260: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
c270: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 NTL_WAL_BLOCK] i
c280: 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 s a signal to th
c290: 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 e VFS layer that
c2a0: 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 it might.** be
c2b0: 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 advantageous to
c2c0: 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 block on the nex
c2d0: 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 t WAL lock if th
c2e0: 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d e lock is not im
c2f0: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 mediately.** ava
c300: 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c ilable. The WAL
c310: 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 subsystem issue
c320: 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 s this signal du
c330: 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 ring rare.** cir
c340: 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 cumstances in or
c350: 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f der to fix a pro
c360: 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 blem with priori
c370: 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a ty inversion..**
c380: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 Applications sh
c390: 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d ould <em>not</em
c3a0: 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d > use this file-
c3b0: 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c control..**.** <
c3c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
c3d0: 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 L_ZIPVFS]].** Th
c3e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
c3f0: 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 ZIPVFS] opcode i
c400: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 s implemented by
c410: 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c zipvfs only. Al
c420: 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 l other.** VFS s
c430: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c hould return SQL
c440: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 ITE_NOTFOUND for
c450: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a this opcode..**
c460: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
c470: 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 _FCNTL_RBU]].**
c480: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
c490: 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 L_RBU] opcode is
c4a0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 implemented by
c4b0: 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 the special VFS
c4c0: 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 used by.** the R
c4d0: 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c BU extension onl
c4e0: 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 y. All other VF
c4f0: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 S should return
c500: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 SQLITE_NOTFOUND
c510: 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f for.** this opco
c520: 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e de. .**.** <li>
c530: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 [[SQLITE_FCNTL_B
c540: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 EGIN_ATOMIC_WRIT
c550: 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 E]].** If the [S
c560: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 QLITE_FCNTL_BEGI
c570: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 N_ATOMIC_WRITE]
c580: 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73 20 53 opcode returns S
c590: 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e 0a 2a QLITE_OK, then.*
c5a0: 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 * the file descr
c5b0: 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65 64 20 iptor is placed
c5c0: 69 6e 20 22 62 61 74 63 68 20 77 72 69 74 65 20 in "batch write
c5d0: 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a 2a 20 mode", which.**
c5e0: 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73 65 71 means all subseq
c5f0: 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61 uent write opera
c600: 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20 64 65 tions will be de
c610: 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e 65 0a ferred and done.
c620: 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20 61 74 ** atomically at
c630: 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c 49 54 the next [SQLIT
c640: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 E_FCNTL_COMMIT_A
c650: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20 20 53 TOMIC_WRITE]. S
c660: 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74 20 64 ystems.** that d
c670: 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 62 61 o not support ba
c680: 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69 74 65 tch atomic write
c690: 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 s will return SQ
c6a0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e 0a 2a LITE_NOTFOUND..*
c6b0: 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 73 * ^Following a s
c6c0: 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49 54 45 uccessful SQLITE
c6d0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f _FCNTL_BEGIN_ATO
c6e0: 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20 70 72 MIC_WRITE and pr
c6f0: 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6c ior to.** the cl
c700: 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 43 osing [SQLITE_FC
c710: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 NTL_COMMIT_ATOMI
c720: 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a 20 5b C_WRITE] or.** [
c730: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c SQLITE_FCNTL_ROL
c740: 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 LBACK_ATOMIC_WRI
c750: 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c TE], SQLite will
c760: 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 53 20 make.** no VFS
c770: 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 73 20 interface calls
c780: 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c on the same [sql
c790: 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c 65 20 ite3_file] file
c7a0: 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20 65 78 descriptor.** ex
c7b0: 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73 20 74 cept for calls t
c7c0: 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d 65 74 o the xWrite met
c7d0: 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46 69 6c hod and the xFil
c7e0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a eControl method.
c7f0: 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f ** with [SQLITE_
c800: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d FCNTL_SIZE_HINT]
c810: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
c820: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 LITE_FCNTL_COMMI
c830: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d T_ATOMIC_WRITE]]
c840: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
c850: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f FCNTL_COMMIT_ATO
c860: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 MIC_WRITE] opcod
c870: 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 e causes all wri
c880: 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 te.** operations
c890: 20 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 since the previ
c8a0: 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 ous successful c
c8b0: 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 all to .** [SQLI
c8c0: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 TE_FCNTL_BEGIN_A
c8d0: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 TOMIC_WRITE] to
c8e0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61 74 6f be performed ato
c8f0: 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 69 73 mically..** This
c900: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 file control re
c910: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
c920: 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 ] if and only if
c930: 20 74 68 65 20 77 72 69 74 65 73 20 77 65 72 65 the writes were
c940: 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72 6d 65 .** all performe
c950: 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 d successfully a
c960: 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63 6f 6d nd have been com
c970: 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73 69 73 mitted to persis
c980: 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a 2a 2a tent storage..**
c990: 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 ^Regardless of
c9a0: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 whether or not i
c9b0: 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 2c t is successful,
c9c0: 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 this file contr
c9d0: 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68 65 20 ol takes.** the
c9e0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 file descriptor
c9f0: 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 out of batch wri
ca00: 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61 74 20 te mode so that
ca10: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a all subsequent.*
ca20: 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f * write operatio
ca30: 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 ns are independe
ca40: 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 nt..** ^SQLite w
ca50: 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 ill never invoke
ca60: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f SQLITE_FCNTL_CO
ca70: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 MMIT_ATOMIC_WRIT
ca80: 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 E without.** a p
ca90: 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 rior successful
caa0: 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f call to [SQLITE_
cab0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d FCNTL_BEGIN_ATOM
cac0: 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a IC_WRITE]..**.**
cad0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
cae0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f NTL_ROLLBACK_ATO
caf0: 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 MIC_WRITE]].** T
cb00: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
cb10: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 _ROLLBACK_ATOMIC
cb20: 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 63 _WRITE] opcode c
cb30: 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65 0a auses all write.
cb40: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73 69 ** operations si
cb50: 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f 75 73 nce the previous
cb60: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
cb70: 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f to .** [SQLITE_
cb80: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d FCNTL_BEGIN_ATOM
cb90: 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65 20 IC_WRITE] to be
cba0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 rolled back..**
cbb0: 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 ^This file contr
cbc0: 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66 69 6c ol takes the fil
cbd0: 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75 74 e descriptor out
cbe0: 20 6f 66 20 62 61 74 63 68 20 77 72 69 74 65 20 of batch write
cbf0: 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61 74 20 mode.** so that
cc00: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77 all subsequent w
cc10: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 rite operations
cc20: 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e are independent.
cc30: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
cc40: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53 51 never invoke SQ
cc50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 LITE_FCNTL_ROLLB
cc60: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 ACK_ATOMIC_WRITE
cc70: 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72 without.** a pr
cc80: 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 ior successful c
cc90: 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46 all to [SQLITE_F
cca0: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 CNTL_BEGIN_ATOMI
ccb0: 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 C_WRITE]..**.**
ccc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
ccd0: 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 5d TL_LOCK_TIMEOUT]
cce0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
ccf0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 _FCNTL_LOCK_TIME
cd00: 4f 55 54 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 OUT] opcode caus
cd10: 65 73 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6f es attempts to o
cd20: 62 74 61 69 6e 0a 2a 2a 20 61 20 66 69 6c 65 20 btain.** a file
cd30: 6c 6f 63 6b 20 75 73 69 6e 67 20 74 68 65 20 78 lock using the x
cd40: 4c 6f 63 6b 20 6f 72 20 78 53 68 6d 4c 6f 63 6b Lock or xShmLock
cd50: 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20 methods of the
cd60: 56 46 53 20 74 6f 20 77 61 69 74 0a 2a 2a 20 66 VFS to wait.** f
cd70: 6f 72 20 75 70 20 74 6f 20 4d 20 6d 69 6c 6c 69 or up to M milli
cd80: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 66 seconds before f
cd90: 61 69 6c 69 6e 67 2c 20 77 68 65 72 65 20 4d 20 ailing, where M
cda0: 69 73 20 74 68 65 20 73 69 6e 67 6c 65 20 0a 2a is the single .*
cdb0: 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 * unsigned integ
cdc0: 65 72 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a er parameter..**
cdd0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </ul>.*/.#defin
cde0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c e SQLITE_FCNTL_L
cdf0: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 OCKSTATE
ce00: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
ce10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 SQLITE_FCNTL_GE
ce20: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
ce30: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
ce40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 SQLITE_FCNTL_SET
ce50: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 _LOCKPROXYFILE
ce60: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
ce70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 QLITE_FCNTL_LAST
ce80: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 _ERRNO
ce90: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
cea0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f LITE_FCNTL_SIZE_
ceb0: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 HINT
cec0: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 5.#define SQL
ced0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f ITE_FCNTL_CHUNK_
cee0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 SIZE
cef0: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 6.#define SQLI
cf00: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f TE_FCNTL_FILE_PO
cf10: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 INTER
cf20: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 7.#define SQLIT
cf30: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 E_FCNTL_SYNC_OMI
cf40: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 TTED
cf50: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
cf60: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f _FCNTL_WIN32_AV_
cf70: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 RETRY 9
cf80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
cf90: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 FCNTL_PERSIST_WA
cfa0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a L 10.
cfb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
cfc0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 CNTL_OVERWRITE
cfd0: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 11.#
cfe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
cff0: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 NTL_VFSNAME
d000: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 12.#d
d010: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
d020: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 TL_POWERSAFE_OVE
d030: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 RWRITE 13.#de
d040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
d050: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 L_PRAGMA
d060: 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 14.#def
d070: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
d080: 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 _BUSYHANDLER
d090: 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 15.#defi
d0a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
d0b0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 TEMPFILENAME
d0c0: 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 16.#defin
d0d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d e SQLITE_FCNTL_M
d0e0: 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 MAP_SIZE
d0f0: 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 18.#define
d100: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 SQLITE_FCNTL_TR
d110: 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ACE
d120: 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 19.#define
d130: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 SQLITE_FCNTL_HAS
d140: 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 _MOVED
d150: 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 20.#define S
d160: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 QLITE_FCNTL_SYNC
d170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
d180: 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 21.#define SQ
d190: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 LITE_FCNTL_COMMI
d1a0: 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 T_PHASETWO
d1b0: 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 22.#define SQL
d1c0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
d1d0: 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 SET_HANDLE
d1e0: 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 23.#define SQLI
d1f0: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f TE_FCNTL_WAL_BLO
d200: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CK
d210: 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 24.#define SQLIT
d220: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 E_FCNTL_ZIPVFS
d230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
d240: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
d250: 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 _FCNTL_RBU
d260: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 26
d270: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d280: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 FCNTL_VFS_POINTE
d290: 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a R 27.
d2a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
d2b0: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 CNTL_JOURNAL_POI
d2c0: 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 23 NTER 28.#
d2d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
d2e0: 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 NTL_WIN32_GET_HA
d2f0: 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23 64 NDLE 29.#d
d300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
d310: 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20 20 TL_PDB
d320: 20 20 20 20 20 20 20 20 20 20 33 30 0a 23 64 65 30.#de
d330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
d340: 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 L_BEGIN_ATOMIC_W
d350: 52 49 54 45 20 20 20 20 20 33 31 0a 23 64 65 66 RITE 31.#def
d360: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
d370: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 _COMMIT_ATOMIC_W
d380: 52 49 54 45 20 20 20 20 33 32 0a 23 64 65 66 69 RITE 32.#defi
d390: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
d3a0: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f ROLLBACK_ATOMIC_
d3b0: 57 52 49 54 45 20 20 33 33 0a 23 64 65 66 69 6e WRITE 33.#defin
d3c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c e SQLITE_FCNTL_L
d3d0: 4f 43 4b 5f 54 49 4d 45 4f 55 54 20 20 20 20 20 OCK_TIMEOUT
d3e0: 20 20 20 20 20 20 33 34 0a 0a 2f 2a 20 64 65 70 34../* dep
d3f0: 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f recated names */
d400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d410: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c GET_LOCKPROXYFIL
d420: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 E SQLITE_FC
d430: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 NTL_GET_LOCKPROX
d440: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 YFILE.#define SQ
d450: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f LITE_SET_LOCKPRO
d460: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 XYFILE SQLI
d470: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 TE_FCNTL_SET_LOC
d480: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 KPROXYFILE.#defi
d490: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 ne SQLITE_LAST_E
d4a0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 RRNO
d4b0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 SQLITE_FCNTL_LA
d4c0: 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a ST_ERRNO.../*.**
d4d0: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 CAPI3REF: Mutex
d4e0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 Handle.**.** Th
d4f0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 e mutex module w
d500: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 ithin SQLite def
d510: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 ines [sqlite3_mu
d520: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a tex] to be an.**
d530: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 abstract type f
d540: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 or a mutex objec
d550: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 t. The SQLite c
d560: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a ore never looks.
d570: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e ** at the intern
d580: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f al representatio
d590: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 n of an [sqlite3
d5a0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c _mutex]. It onl
d5b0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 y.** deals with
d5c0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 pointers to the
d5d0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 [sqlite3_mutex]
d5e0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 object..**.** Mu
d5f0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 texes are create
d600: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
d610: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e _mutex_alloc()].
d620: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
d630: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ct sqlite3_mutex
d640: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a sqlite3_mutex;.
d650: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
d660: 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 Loadable Extens
d670: 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 ion Thunk.**.**
d680: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 A pointer to the
d690: 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f opaque sqlite3_
d6a0: 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 api_routines str
d6b0: 75 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64 ucture is passed
d6c0: 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 as.** the third
d6d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e parameter to en
d6e0: 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c try points of [l
d6f0: 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f oadable extensio
d700: 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 ns]. This.** st
d710: 72 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 ructure must be
d720: 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 typedefed in ord
d730: 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e er to work aroun
d740: 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 d compiler warni
d750: 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 ngs.** on some p
d760: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 latforms..*/.typ
d770: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
d780: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 te3_api_routines
d790: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 sqlite3_api_rou
d7a0: 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tines;../*.** CA
d7b0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
d7c0: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a face Object.**.*
d7d0: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
d7e0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
d7f0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 object defines
d800: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 the interface be
d810: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c tween.** the SQL
d820: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 ite core and the
d830: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 underlying oper
d840: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 ating system. T
d850: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 he "vfs".** in t
d860: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f he name of the o
d870: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 bject stands for
d880: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 "virtual file s
d890: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 ystem". See.**
d8a0: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 the [VFS | VFS d
d8b0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f ocumentation] fo
d8c0: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d r further inform
d8d0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ation..**.** The
d8e0: 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 20 69 VFS interface i
d8f0: 73 20 73 6f 6d 65 74 69 6d 65 73 20 65 78 74 65 s sometimes exte
d900: 6e 64 65 64 20 62 79 20 61 64 64 69 6e 67 20 6e nded by adding n
d910: 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74 6f 0a ew methods onto.
d920: 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20 45 61 63 ** the end. Eac
d930: 68 20 74 69 6d 65 20 73 75 63 68 20 61 6e 20 65 h time such an e
d940: 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72 73 2c xtension occurs,
d950: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 the iVersion fi
d960: 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72 65 6d eld.** is increm
d970: 65 6e 74 65 64 2e 20 20 54 68 65 20 69 56 65 72 ented. The iVer
d980: 73 69 6f 6e 20 76 61 6c 75 65 20 73 74 61 72 74 sion value start
d990: 65 64 20 6f 75 74 20 61 73 20 31 20 69 6e 0a 2a ed out as 1 in.*
d9a0: 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f * SQLite [versio
d9b0: 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64 61 74 n 3.5.0] on [dat
d9c0: 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68 65 6e eof:3.5.0], then
d9d0: 20 69 6e 63 72 65 61 73 65 64 20 74 6f 20 32 0a increased to 2.
d9e0: 2a 2a 20 77 69 74 68 20 53 51 4c 69 74 65 20 5b ** with SQLite [
d9f0: 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d 20 6f version 3.7.0] o
da00: 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 30 5d n [dateof:3.7.0]
da10: 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e 63 72 65 , and then incre
da20: 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77 69 74 ased.** to 3 wit
da30: 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f h SQLite [versio
da40: 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64 61 74 n 3.7.6] on [dat
da50: 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41 64 64 eof:3.7.6]. Add
da60: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a itional fields.*
da70: 2a 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 * may be appende
da80: 64 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 d to the sqlite3
da90: 5f 76 66 73 20 6f 62 6a 65 63 74 20 61 6e 64 20 _vfs object and
daa0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c the iVersion val
dab0: 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72 65 61 ue.** may increa
dac0: 73 65 20 61 67 61 69 6e 20 69 6e 20 66 75 74 75 se again in futu
dad0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
dae0: 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 QLite..** Note t
daf0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 hat the structur
db00: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 e.** of the sqli
db10: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 te3_vfs object c
db20: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 hanges in the tr
db30: 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a ansition from.**
db40: 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e SQLite [version
db50: 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65 72 73 3.5.9] to [vers
db60: 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20 5b 64 ion 3.6.0] on [d
db70: 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a 2a 20 ateof:3.6.0].**
db80: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 and yet the iVer
db90: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e sion field was n
dba0: 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a ot modified..**.
dbb0: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 ** The szOsFile
dbc0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a field is the siz
dbd0: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 e of the subclas
dbe0: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c sed [sqlite3_fil
dbf0: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 e].** structure
dc00: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 used by this VFS
dc10: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 . mxPathname is
dc20: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e the maximum len
dc30: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 gth of.** a path
dc40: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 name in this VFS
dc50: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 ..**.** Register
dc60: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f ed sqlite3_vfs o
dc70: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 bjects are kept
dc80: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 on a linked list
dc90: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 formed by.** th
dca0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
dcb0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 The [sqlite3_v
dcc0: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a fs_register()].*
dcd0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 * and [sqlite3_v
dce0: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d fs_unregister()]
dcf0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 interfaces mana
dd00: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 ge this list.**
dd10: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 in a thread-safe
dd20: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 way. The [sqli
dd30: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 te3_vfs_find()]
dd40: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 interface.** sea
dd50: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 rches the list.
dd60: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 Neither the app
dd70: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f lication code no
dd80: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 r the VFS.** imp
dd90: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 lementation shou
dda0: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 ld use the pNext
ddb0: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
ddc0: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 The pNext field
ddd0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c is the only fiel
dde0: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 d in the sqlite3
ddf0: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 _vfs.** structur
de00: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 e that SQLite wi
de10: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 ll ever modify.
de20: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c SQLite will onl
de30: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d y access.** or m
de40: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 odify this field
de50: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 while holding a
de60: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 particular stat
de70: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 ic mutex..** The
de80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
de90: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 uld never modify
dea0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e anything within
deb0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
dec0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 .** object once
ded0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 the object has b
dee0: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a een registered..
def0: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 **.** The zName
df00: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 field holds the
df10: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 name of the VFS
df20: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d module. The nam
df30: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 e must.** be uni
df40: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 que across all V
df50: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a FS modules..**.*
df60: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e * [[sqlite3_vfs.
df70: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 xOpen]].** ^SQLi
df80: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 te guarantees th
df90: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 at the zFilename
dfa0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f parameter to xO
dfb0: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 pen.** is either
dfc0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
dfd0: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e or string obtain
dfe0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c ed.** from xFull
dff0: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 Pathname() with
e000: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 an optional suff
e010: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 ix added..** ^If
e020: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 a suffix is add
e030: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e ed to the zFilen
e040: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 ame parameter, i
e050: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 t will.** consis
e060: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d t of a single "-
e070: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c " character foll
e080: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 owed by no more
e090: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 than.** 11 alpha
e0a0: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 numeric and/or "
e0b0: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a -" characters..*
e0c0: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 * ^SQLite furthe
e0d0: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 r guarantees tha
e0e0: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 t.** the string
e0f0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e will be valid an
e100: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 d unchanged unti
e110: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a l xClose() is.**
e120: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 called. Because
e130: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 of the previous
e140: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 sentence,.** th
e150: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d e [sqlite3_file]
e160: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 can safely stor
e170: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 e a pointer to t
e180: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 he.** filename i
e190: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 f it needs to re
e1a0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e member the filen
e1b0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 ame for some rea
e1c0: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a son..** If the z
e1d0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
e1e0: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 er to xOpen is a
e1f0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
e200: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 en xOpen.** must
e210: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 invent its own
e220: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 temporary name f
e230: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 or the file. ^W
e240: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 henever the .**
e250: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 xFilename parame
e260: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 ter is NULL it w
e270: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 ill also be the
e280: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a case that the.**
e290: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
e2a0: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 will include [S
e2b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
e2c0: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a EONCLOSE]..**.**
e2d0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d The flags argum
e2e0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 ent to xOpen() i
e2f0: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 ncludes all bits
e300: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 set in.** the f
e310: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
e320: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
e330: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 2()]. Or if [sq
e340: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a lite3_open()].**
e350: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 or [sqlite3_ope
e360: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 n16()] is used,
e370: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 then flags inclu
e380: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 des at least.**
e390: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
e3a0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 DWRITE] | [SQLIT
e3b0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 E_OPEN_CREATE].
e3c0: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f .** If xOpen() o
e3d0: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 pens a file read
e3e0: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 -only then it se
e3f0: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f ts *pOutFlags to
e400: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c .** include [SQL
e410: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
e420: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 Y]. Other bits
e430: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 in *pOutFlags ma
e440: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 y be set..**.**
e450: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c ^(SQLite will al
e460: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 so add one of th
e470: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 e following flag
e480: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 s to the xOpen()
e490: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 .** call, depend
e4a0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 ing on the objec
e4b0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a t being opened:.
e4c0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
e4d0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
e4e0: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 _MAIN_DB].** <li
e4f0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
e500: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a MAIN_JOURNAL].**
e510: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
e520: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 PEN_TEMP_DB].**
e530: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
e540: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d EN_TEMP_JOURNAL]
e550: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
e560: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 E_OPEN_TRANSIENT
e570: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
e580: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f QLITE_OPEN_SUBJO
e590: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 URNAL].** <li>
e5a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 [SQLITE_OPEN_MAS
e5b0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 TER_JOURNAL].**
e5c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
e5d0: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e EN_WAL].** </ul>
e5e0: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c )^.**.** The fil
e5f0: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 e I/O implementa
e600: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 tion can use the
e610: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 object type fla
e620: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 gs to.** change
e630: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 the way it deals
e640: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f with files. Fo
e650: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 r example, an ap
e660: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 plication.** tha
e670: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 t does not care
e680: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f about crash reco
e690: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b very or rollback
e6a0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 might make.** t
e6b0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 he open of a jou
e6c0: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f rnal file a no-o
e6d0: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 p. Writes to th
e6e0: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 is journal would
e6f0: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f .** also be no-o
e700: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 ps, and any atte
e710: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 mpt to read the
e720: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 journal would re
e730: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 turn.** SQLITE_I
e740: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d OERR. Or the im
e750: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 plementation mig
e760: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 ht recognize tha
e770: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 t a database.**
e780: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 file will be doi
e790: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 ng page-aligned
e7a0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 sector reads and
e7b0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e writes in a ran
e7c0: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 dom.** order and
e7d0: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 set up its I/O
e7e0: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 subsystem accord
e7f0: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c ingly..**.** SQL
e800: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 ite might also a
e810: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f dd one of the fo
e820: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f llowing flags to
e830: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f the xOpen metho
e840: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a d:.**.** <ul>.**
e850: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
e860: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
e870: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
e880: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 E_OPEN_EXCLUSIVE
e890: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a ].** </ul>.**.**
e8a0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 The [SQLITE_OPE
e8b0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
e8c0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 flag means the
e8d0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a file should be.*
e8e0: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 * deleted when i
e8f0: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 t is closed. ^T
e900: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
e910: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a DELETEONCLOSE].*
e920: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f * will be set fo
e930: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 r TEMP databases
e940: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e and their journ
e950: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a als, transient.*
e960: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 * databases, and
e970: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a subjournals..**
e980: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
e990: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d _OPEN_EXCLUSIVE]
e9a0: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 flag is always
e9b0: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 used in conjunct
e9c0: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ion.** with the
e9d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 [SQLITE_OPEN_CRE
e9e0: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 ATE] flag, which
e9f0: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 are both direct
ea00: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 ly.** analogous
ea10: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e to the O_EXCL an
ea20: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 d O_CREAT flags
ea30: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 of the POSIX ope
ea40: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 n().** API. The
ea50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 SQLITE_OPEN_EXC
ea60: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 LUSIVE flag, whe
ea70: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 n paired with th
ea80: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 e .** SQLITE_OPE
ea90: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 N_CREATE, is use
eaa0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 d to indicate th
eab0: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 at file should a
eac0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 lways.** be crea
ead0: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 ted, and that it
eae0: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 is an error if
eaf0: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 it already exist
eb00: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e s..** It is <i>n
eb10: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 ot</i> used to i
eb20: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 ndicate the file
eb30: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 should be opene
eb40: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 d .** for exclus
eb50: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a ive access..**.*
eb60: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 * ^At least szOs
eb70: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 File bytes of me
eb80: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 mory are allocat
eb90: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 ed by SQLite.**
eba0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 to hold the [sq
ebb0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 lite3_file] stru
ebc0: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 cture passed as
ebd0: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 the third.** arg
ebe0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 ument to xOpen.
ebf0: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f The xOpen metho
ec00: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 d does not have
ec10: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 to.** allocate t
ec20: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 he structure; it
ec30: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c should just fil
ec40: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 l it in. Note t
ec50: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e hat.** the xOpen
ec60: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 method must set
ec70: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c the sqlite3_fil
ec80: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 e.pMethods to ei
ec90: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 ther.** a valid
eca0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
ecb0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 ods] object or t
ecc0: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d o NULL. xOpen m
ecd0: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 ust do.** this e
ece0: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 ven if the open
ecf0: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 fails. SQLite e
ed00: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 xpects that the
ed10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 sqlite3_file.pMe
ed20: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 thods.** element
ed30: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 will be valid a
ed40: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 fter xOpen retur
ed50: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ns regardless of
ed60: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 the success.**
ed70: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 or failure of th
ed80: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a e xOpen call..**
ed90: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 .** [[sqlite3_vf
eda0: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e s.xAccess]].** ^
edb0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 The flags argume
edc0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 nt to xAccess()
edd0: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 may be [SQLITE_A
ede0: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a CCESS_EXISTS].**
edf0: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 to test for the
ee00: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 existence of a
ee10: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 file, or [SQLITE
ee20: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
ee30: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 E] to.** test wh
ee40: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 ether a file is
ee50: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 readable and wri
ee60: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 table, or [SQLIT
ee70: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a E_ACCESS_READ].*
ee80: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 * to test whethe
ee90: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c r a file is at l
eea0: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 east readable.
eeb0: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 The file can be
eec0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e a.** directory.
eed0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 .**.** ^SQLite w
eee0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 ill always alloc
eef0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 ate at least mxP
ef00: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 athname+1 bytes
ef10: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 for the.** outpu
ef20: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 t buffer xFullPa
ef30: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 thname. The exa
ef40: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f ct size of the o
ef50: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 utput buffer.**
ef60: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 is also passed a
ef70: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f s a parameter to
ef80: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 both methods.
ef90: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 If the output bu
efa0: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c ffer.** is not l
efb0: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 arge enough, [SQ
efc0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 LITE_CANTOPEN] s
efd0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 hould be returne
efe0: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 d. Since this is
eff0: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 .** handled as a
f000: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 fatal error by
f010: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c SQLite, vfs impl
f020: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 ementations shou
f030: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 ld endeavor.** t
f040: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 o prevent this b
f050: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 y setting mxPath
f060: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 name to a suffic
f070: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c iently large val
f080: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 ue..**.** The xR
f090: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c andomness(), xSl
f0a0: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 eep(), xCurrentT
f0b0: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 ime(), and xCurr
f0c0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a entTimeInt64().*
f0d0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 * interfaces are
f0e0: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 not strictly a
f0f0: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 part of the file
f100: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 system, but they
f110: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 are.** included
f120: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 in the VFS stru
f130: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 cture for comple
f140: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 teness..** The x
f150: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e Randomness() fun
f160: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 ction attempts t
f170: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 o return nBytes
f180: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 bytes.** of good
f190: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e -quality randomn
f1a0: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 ess into zOut.
f1b0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 The return value
f1c0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 is.** the actua
f1d0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 l number of byte
f1e0: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 s of randomness
f1f0: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 obtained..** The
f200: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 xSleep() method
f210: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c causes the call
f220: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c ing thread to sl
f230: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 eep for at.** le
f240: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ast the number o
f250: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 f microseconds g
f260: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 iven. ^The xCur
f270: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 rentTime().** me
f280: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a thod returns a J
f290: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 ulian Day Number
f2a0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 for the current
f2b0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 date and time a
f2c0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 s.** a floating
f2d0: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 point value..**
f2e0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d ^The xCurrentTim
f2f0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 eInt64() method
f300: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 returns, as an i
f310: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 nteger, the Juli
f320: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 an.** Day Number
f330: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 multiplied by 8
f340: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 6400000 (the num
f350: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f ber of milliseco
f360: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d nds in .** a 24-
f370: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 hour day). .**
f380: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 ^SQLite will use
f390: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d the xCurrentTim
f3a0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 eInt64() method
f3b0: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 to get the curre
f3c0: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 nt.** date and t
f3d0: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 ime if that meth
f3e0: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 od is available
f3f0: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 (if iVersion is
f400: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 2 or .** greater
f410: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f and the functio
f420: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 n pointer is not
f430: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 NULL) and will
f440: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 fall back.** to
f450: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 xCurrentTime() i
f460: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e f xCurrentTimeIn
f470: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c t64() is unavail
f480: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 able..**.** ^The
f490: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 xSetSystemCall(
f4a0: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c ), xGetSystemCal
f4b0: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 l(), and xNestSy
f4c0: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 stemCall() inter
f4d0: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 faces.** are not
f4e0: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c used by the SQL
f4f0: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 ite core. These
f500: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 optional interf
f510: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 aces are provide
f520: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 d.** by some VFS
f530: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 es to facilitate
f540: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 testing of the
f550: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 VFS code. By ove
f560: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 rriding .** syst
f570: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 em calls with fu
f580: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 nctions under it
f590: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 s control, a tes
f5a0: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a t program can.**
f5b0: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 simulate faults
f5c0: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 and error condi
f5d0: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 tions that would
f5e0: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 otherwise be di
f5f0: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d fficult.** or im
f600: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 possible to indu
f610: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 ce. The set of
f620: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 system calls tha
f630: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 t can be overrid
f640: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 den.** varies fr
f650: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e om one VFS to an
f660: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 other, and from
f670: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 one version of t
f680: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 he same VFS to t
f690: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 he.** next. App
f6a0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 lications that u
f6b0: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 se these interfa
f6c0: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 ces must be prep
f6d0: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 ared for any.**
f6e0: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 or all of these
f6f0: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 interfaces to be
f700: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 NULL or for the
f710: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 ir behavior to c
f720: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e hange.** from on
f730: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 e release to the
f740: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 next. Applicat
f750: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 ions must not at
f760: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a tempt to access.
f770: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 ** any of these
f780: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 methods if the i
f790: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 Version of the V
f7a0: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 FS is less than
f7b0: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 3..*/.typedef st
f7c0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 ruct sqlite3_vfs
f7d0: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 sqlite3_vfs;.ty
f7e0: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c pedef void (*sql
f7f0: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 ite3_syscall_ptr
f800: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 )(void);.struct
f810: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 sqlite3_vfs {.
f820: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 int iVersion;
f830: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 /* Stru
f840: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 cture version nu
f850: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 mber (currently
f860: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 3) */. int szOs
f870: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 File;
f880: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 /* Size of subc
f890: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 lassed sqlite3_f
f8a0: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 ile */. int mxP
f8b0: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 athname;
f8c0: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c /* Maximum fil
f8d0: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 e pathname lengt
f8e0: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 h */. sqlite3_v
f8f0: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 fs *pNext;
f900: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 /* Next register
f910: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 ed VFS */. cons
f920: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 t char *zName;
f930: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
f940: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c this virtual fil
f950: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f e system */. vo
f960: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 id *pAppData;
f970: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 /* Pointe
f980: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e r to application
f990: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a -specific data *
f9a0: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 /. int (*xOpen)
f9b0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
f9c0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
f9d0: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c , sqlite3_file*,
f9e0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
f9f0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a int flags, int *
fa00: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e pOutFlags);. in
fa10: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c t (*xDelete)(sql
fa20: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
fa30: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
fa40: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e t syncDir);. in
fa50: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c t (*xAccess)(sql
fa60: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
fa70: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
fa80: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 t flags, int *pR
fa90: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a esOut);. int (*
faa0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 xFullPathname)(s
fab0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
fac0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
fad0: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a int nOut, char *
fae0: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 zOut);. void *(
faf0: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 *xDlOpen)(sqlite
fb00: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
fb10: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a ar *zFilename);.
fb20: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f void (*xDlErro
fb30: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c r)(sqlite3_vfs*,
fb40: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 int nByte, char
fb50: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f *zErrMsg);. vo
fb60: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 id (*(*xDlSym)(s
fb70: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 qlite3_vfs*,void
fb80: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
fb90: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a Symbol))(void);.
fba0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 void (*xDlClos
fbb0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
fbc0: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 void*);. int (
fbd0: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 *xRandomness)(sq
fbe0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 lite3_vfs*, int
fbf0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 nByte, char *zOu
fc00: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 t);. int (*xSle
fc10: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ep)(sqlite3_vfs*
fc20: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e , int microsecon
fc30: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 ds);. int (*xCu
fc40: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 rrentTime)(sqlit
fc50: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a e3_vfs*, double*
fc60: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c );. int (*xGetL
fc70: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 astError)(sqlite
fc80: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 3_vfs*, int, cha
fc90: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 r *);. /*. **
fca0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
fcb0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
fcc0: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 1 of the sqlite
fcd0: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a _vfs object. **
fce0: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 definition. Th
fcf0: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 ose that follow
fd00: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 are added in ver
fd10: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a sion 2 or later.
fd20: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 */. int (*xCu
fd30: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 rrentTimeInt64)(
fd40: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 sqlite3_vfs*, sq
fd50: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 lite3_int64*);.
fd60: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 /*. ** The met
fd70: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 hods above are i
fd80: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 n versions 1 and
fd90: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 2 of the sqlite
fda0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a _vfs object.. *
fdb0: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 * Those below ar
fdc0: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 e for version 3
fdd0: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a and greater.. *
fde0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 /. int (*xSetSy
fdf0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 stemCall)(sqlite
fe00: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
fe10: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 ar *zName, sqlit
fe20: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b e3_syscall_ptr);
fe30: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 . sqlite3_sysca
fe40: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 ll_ptr (*xGetSys
fe50: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 temCall)(sqlite3
fe60: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
fe70: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e r *zName);. con
fe80: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 st char *(*xNext
fe90: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 SystemCall)(sqli
fea0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
feb0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 char *zName);.
fec0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 /*. ** The meth
fed0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e ods above are in
fee0: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f versions 1 thro
fef0: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c ugh 3 of the sql
ff00: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a ite_vfs object..
ff10: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 ** New fields
ff20: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 may be appended
ff30: 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f in future versio
ff40: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f ns. The iVersio
ff50: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c n. ** value wil
ff60: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e l increment when
ff70: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e ever this happen
ff80: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a s. . */.};../*.
ff90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 ** CAPI3REF: Fla
ffa0: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 gs for the xAcce
ffb0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a ss VFS method.**
ffc0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 .** These intege
ffd0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 r constants can
ffe0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 be used as the t
fff0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
10000 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 o.** the xAccess
10010 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 method of an [s
10020 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
10030 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d ct. They determ
10040 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 ine.** what kind
10050 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 of permissions
10060 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
10070 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f od is looking fo
10080 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 r..** With SQLIT
10090 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c E_ACCESS_EXISTS,
100a0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
100b0 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 hod.** simply ch
100c0 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 ecks whether the
100d0 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a file exists..**
100e0 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 With SQLITE_ACC
100f0 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 ESS_READWRITE, t
10100 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
10110 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 d.** checks whet
10120 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 her the named di
10130 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 rectory is both
10140 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 readable and wri
10150 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 table.** (in oth
10160 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c er words, if fil
10170 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c es can be added,
10180 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 removed, and re
10190 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 named within.**
101a0 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a the directory)..
101b0 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 ** The SQLITE_AC
101c0 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 CESS_READWRITE c
101d0 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 onstant is curre
101e0 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 ntly used only b
101f0 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 y the.** [temp_s
10200 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 tore_directory p
10210 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 ragma], though t
10220 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 his could change
10230 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 in a future.**
10240 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
10250 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 e..** With SQLIT
10260 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 E_ACCESS_READ, t
10270 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
10280 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 d.** checks whet
10290 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 her the file is
102a0 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 readable. The S
102b0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
102c0 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a D constant is.**
102d0 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 currently unuse
102e0 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 d, though it mig
102f0 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 ht be used in a
10300 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
10310 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a f.** SQLite..*/.
10320 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
10330 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 CCESS_EXISTS
10340 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
10350 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
10360 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 E 1 /* Used by
10370 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f PRAGMA temp_sto
10380 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a re_directory */.
10390 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
103a0 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 CCESS_READ
103b0 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 2 /* Unused */
103c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
103d0 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 : Flags for the
103e0 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 xShmLock VFS met
103f0 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 hod.**.** These
10400 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
10410 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 s define the var
10420 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 ious locking ope
10430 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 rations.** allow
10440 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f ed by the xShmLo
10450 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 ck method of [sq
10460 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
10470 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f ]. The.** follo
10480 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c wing are the onl
10490 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 y legal combinat
104a0 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f ions of flags to
104b0 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b the.** xShmLock
104c0 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c method:.**.** <
104d0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c ul>.** <li> SQL
104e0 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 ITE_SHM_LOCK | S
104f0 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 QLITE_SHM_SHARED
10500 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
10510 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 _SHM_LOCK | SQLI
10520 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
10530 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
10540 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 _SHM_UNLOCK | SQ
10550 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a LITE_SHM_SHARED.
10560 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
10570 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c SHM_UNLOCK | SQL
10580 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 ITE_SHM_EXCLUSIV
10590 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a E.** </ul>.**.**
105a0 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c When unlocking,
105b0 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 the same SHARED
105c0 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c or EXCLUSIVE fl
105d0 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c ag must be suppl
105e0 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 ied as.** was gi
105f0 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 ven on the corre
10600 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 sponding lock.
10610 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c .**.** The xShmL
10620 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 ock method can t
10630 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 ransition betwee
10640 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 n unlocked and S
10650 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 HARED or.** betw
10660 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 een unlocked and
10670 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 EXCLUSIVE. It
10680 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f cannot transitio
10690 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 n between SHARED
106a0 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 .** and EXCLUSIV
106b0 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 E..*/.#define SQ
106c0 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 LITE_SHM_UNLOCK
106d0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
106e0 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 SQLITE_SHM_LOCK
106f0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
10700 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 e SQLITE_SHM_SHA
10710 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 RED 4.#def
10720 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 ine SQLITE_SHM_E
10730 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f XCLUSIVE 8../
10740 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
10750 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 aximum xShmLock
10760 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 index.**.** The
10770 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 xShmLock method
10780 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d on [sqlite3_io_m
10790 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 ethods] may use
107a0 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 values.** betwee
107b0 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 n 0 and this upp
107c0 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 er bound as its
107d0 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e "offset" argumen
107e0 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 t..** The SQLite
107f0 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 core will never
10800 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 attempt to acqu
10810 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 ire or release a
10820 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 .** lock outside
10830 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a of this range.*
10840 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
10850 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 _SHM_NLOCK
10860 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 8.../*.** CAPI
10870 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 3REF: Initialize
10880 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 The SQLite Libr
10890 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ary.**.** ^The s
108a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
108b0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 e() routine init
108c0 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 ializes the.** S
108d0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 QLite library.
108e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 ^The sqlite3_shu
108f0 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a tdown() routine.
10900 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 ** deallocates a
10910 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 ny resources tha
10920 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 t were allocated
10930 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 by sqlite3_init
10940 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 ialize()..** The
10950 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
10960 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 designed to aid
10970 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 in process initi
10980 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a alization and.**
10990 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 shutdown on emb
109a0 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 edded systems.
109b0 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c Workstation appl
109c0 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a ications using.*
109d0 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c * SQLite normall
109e0 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f y do not need to
109f0 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f invoke either o
10a00 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
10a10 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 ..**.** A call t
10a20 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 o sqlite3_initia
10a30 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 lize() is an "ef
10a40 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 fective" call if
10a50 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 it is.** the fi
10a60 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 rst time sqlite3
10a70 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
10a80 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 invoked during
10a90 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a the lifetime of.
10aa0 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 ** the process,
10ab0 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 or if it is the
10ac0 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 first time sqlit
10ad0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
10ae0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f is invoked.** fo
10af0 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 llowing a call t
10b00 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
10b10 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e wn(). ^(Only an
10b20 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a effective call.
10b30 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e ** of sqlite3_in
10b40 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 itialize() does
10b50 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 any initializati
10b60 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 on. All other c
10b70 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d alls.** are harm
10b80 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a less no-ops.)^.*
10b90 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 *.** A call to s
10ba0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
10bb0 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 ) is an "effecti
10bc0 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 ve" call if it i
10bd0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 s the first.** c
10be0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
10bf0 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 hutdown() since
10c00 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 the last sqlite3
10c10 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 _initialize().
10c20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 ^(Only.** an eff
10c30 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 ective call to s
10c40 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
10c50 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 ) does any deini
10c60 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 tialization..**
10c70 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 All other valid
10c80 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
10c90 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 _shutdown() are
10ca0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e harmless no-ops.
10cb0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )^.**.** The sql
10cc0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
10cd0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 ) interface is t
10ce0 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 hreadsafe, but s
10cf0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
10d00 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 ).** is not. Th
10d10 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f e sqlite3_shutdo
10d20 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d wn() interface m
10d30 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c ust only be call
10d40 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e ed from a.** sin
10d50 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c gle thread. All
10d60 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 open [database
10d70 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 connections] mus
10d80 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 t be closed and
10d90 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c all.** other SQL
10da0 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 ite resources mu
10db0 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 st be deallocate
10dc0 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b d prior to invok
10dd0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 ing.** sqlite3_s
10de0 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a hutdown()..**.**
10df0 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 Among other thi
10e00 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e ngs, ^sqlite3_in
10e10 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 itialize() will
10e20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 invoke.** sqlite
10e30 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 3_os_init(). Si
10e40 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 milarly, ^sqlite
10e50 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 3_shutdown().**
10e60 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 will invoke sqli
10e70 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a te3_os_end()..**
10e80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
10e90 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f _initialize() ro
10ea0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 utine returns [S
10eb0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
10ec0 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 cess..** ^If for
10ed0 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 some reason, sq
10ee0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
10ef0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 () is unable to
10f00 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 initialize.** th
10f10 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 e library (perha
10f20 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 ps it is unable
10f30 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 to allocate a ne
10f40 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 eded resource su
10f50 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 ch.** as a mutex
10f60 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 ) it returns an
10f70 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 [error code] oth
10f80 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
10f90 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 OK]..**.** ^The
10fa0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
10fb0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 ze() routine is
10fc0 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c called internall
10fd0 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a y by many other.
10fe0 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ** SQLite interf
10ff0 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 aces so that an
11000 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 application usua
11010 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 lly does not nee
11020 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 d to.** invoke s
11030 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
11040 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 e() directly. F
11050 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c or example, [sql
11060 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 ite3_open()].**
11070 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e calls sqlite3_in
11080 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 itialize() so th
11090 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
110a0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 will be automat
110b0 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 ically.** initia
110c0 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 lized when [sqli
110d0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 te3_open()] is c
110e0 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 alled if it has
110f0 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a not be initializ
11100 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 ed.** already.
11110 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c ^However, if SQL
11120 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
11130 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 with the [SQLITE
11140 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a _OMIT_AUTOINIT].
11150 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 ** compile-time
11160 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 option, then the
11170 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 automatic calls
11180 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 to sqlite3_init
11190 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 ialize().** are
111a0 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 omitted and the
111b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
111c0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e call sqlite3_in
111d0 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 itialize() direc
111e0 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 tly.** prior to
111f0 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 using any other
11200 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
11210 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 . For maximum p
11220 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 ortability,.** i
11230 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 t is recommended
11240 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f that applicatio
11250 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 ns always invoke
11260 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
11270 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c ize().** directl
11280 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 y prior to using
11290 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 any other SQLit
112a0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 e interface. Fu
112b0 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a ture releases.**
112c0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 of SQLite may r
112d0 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e equire this. In
112e0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
112f0 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 e behavior exhib
11300 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c ited.** when SQL
11310 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
11320 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 with [SQLITE_OMI
11330 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 T_AUTOINIT] migh
11340 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 t become the.**
11350 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 default behavior
11360 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 in some future
11370 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
11380 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e..**.** The sql
11390 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 ite3_os_init() r
113a0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 outine does oper
113b0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 ating-system spe
113c0 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c cific.** initial
113d0 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 ization of the S
113e0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 QLite library.
113f0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 The sqlite3_os_e
11400 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 nd().** routine
11410 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 undoes the effec
11420 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f t of sqlite3_os_
11430 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c init(). Typical
11440 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 tasks.** perfor
11450 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 med by these rou
11460 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c tines include al
11470 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c location or deal
11480 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 location.** of s
11490 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c tatic resources,
114a0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
114b0 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 of global variab
114c0 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 les,.** setting
114d0 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 up a default [sq
114e0 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c lite3_vfs] modul
114f0 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 e, or setting up
11500 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f .** a default co
11510 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e nfiguration usin
11520 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 g [sqlite3_confi
11530 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 g()]..**.** The
11540 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
11550 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 ld never invoke
11560 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f either sqlite3_o
11570 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 s_init().** or s
11580 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 qlite3_os_end()
11590 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 directly. The a
115a0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
115b0 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a d only invoke.**
115c0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
115d0 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ize() and sqlite
115e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 3_shutdown(). T
115f0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e he sqlite3_os_in
11600 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 it().** interfac
11610 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f e is called auto
11620 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c matically by sql
11630 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
11640 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ) and.** sqlite3
11650 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c _os_end() is cal
11660 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 led by sqlite3_s
11670 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 hutdown(). Appr
11680 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 opriate.** imple
11690 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 mentations for s
116a0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
116b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f and sqlite3_os_
116c0 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 end().** are bui
116d0 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 lt into SQLite w
116e0 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c hen it is compil
116f0 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e ed for Unix, Win
11700 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a dows, or OS/2..*
11710 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 * When [custom b
11720 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f uilds | built fo
11730 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d r other platform
11740 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 s].** (using the
11750 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 [SQLITE_OS_OTHE
11760 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d R=1] compile-tim
11770 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 e.** option) the
11780 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
11790 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 t supply a suita
117a0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
117b0 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 on for.** sqlite
117c0 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 3_os_init() and
117d0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
117e0 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f . An applicatio
117f0 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d n-supplied.** im
11800 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
11810 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
11820 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f ) or sqlite3_os_
11830 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 end().** must re
11840 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
11850 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 on success and
11860 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f some other [erro
11870 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 r code] upon.**
11880 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 failure..*/.int
11890 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
118a0 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 ze(void);.int sq
118b0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 lite3_shutdown(v
118c0 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 oid);.int sqlite
118d0 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 3_os_init(void);
118e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f .int sqlite3_os_
118f0 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a end(void);../*.*
11900 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
11910 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 iguring The SQLi
11920 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a te Library.**.**
11930 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e The sqlite3_con
11940 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
11950 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 is used to make
11960 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 global configura
11970 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 tion.** changes
11980 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 to SQLite in ord
11990 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 er to tune SQLit
119a0 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 e to the specifi
119b0 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 c needs of.** th
119c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 e application.
119d0 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 The default conf
119e0 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 iguration is rec
119f0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 ommended for mos
11a00 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e t.** application
11a10 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f s and so this ro
11a20 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 utine is usually
11a30 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 not necessary.
11a40 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 It is.** provid
11a50 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 ed to support ra
11a60 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 re applications
11a70 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 with unusual nee
11a80 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 ds..**.** <b>The
11a90 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
11aa0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e ) interface is n
11ab0 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 ot threadsafe. T
11ac0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a he application.*
11ad0 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 * must ensure th
11ae0 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 at no other SQLi
11af0 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 te interfaces ar
11b00 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 e invoked by oth
11b10 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 er.** threads wh
11b20 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ile sqlite3_conf
11b30 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e ig() is running.
11b40 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 </b>.**.** The s
11b50 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
11b60 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 interface.** may
11b70 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 only be invoked
11b80 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 prior to librar
11b90 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e y initialization
11ba0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
11bb0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
11bc0 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f or after shutdo
11bd0 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 wn by [sqlite3_s
11be0 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e hutdown()]..** ^
11bf0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 If sqlite3_confi
11c00 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 g() is called af
11c10 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 ter [sqlite3_ini
11c20 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 tialize()] and b
11c30 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 efore.** [sqlite
11c40 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 3_shutdown()] th
11c50 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 en it will retur
11c60 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e n SQLITE_MISUSE.
11c70 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 .** Note, howeve
11c80 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 r, that ^sqlite3
11c90 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 _config() can be
11ca0 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 called as part
11cb0 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d of the.** implem
11cc0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 entation of an a
11cd0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
11ce0 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 ed [sqlite3_os_i
11cf0 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 nit()]..**.** Th
11d00 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
11d10 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to sqlite3_conf
11d20 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 ig() is an integ
11d30 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 er.** [configura
11d40 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 tion option] tha
11d50 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 t determines.**
11d60 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 what property of
11d70 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 SQLite is to be
11d80 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 configured. Su
11d90 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e bsequent argumen
11da0 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e ts.** vary depen
11db0 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e ding on the [con
11dc0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
11dd0 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 n].** in the fir
11de0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a st argument..**.
11df0 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 ** ^When a confi
11e00 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
11e10 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f is set, sqlite3_
11e20 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 config() returns
11e30 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a [SQLITE_OK]..**
11e40 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 ^If the option
11e50 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 is unknown or SQ
11e60 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 Lite is unable t
11e70 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e o set the option
11e80 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f .** then this ro
11e90 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 utine returns a
11ea0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 non-zero [error
11eb0 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 code]..*/.int sq
11ec0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 lite3_config(int
11ed0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , ...);../*.** C
11ee0 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
11ef0 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e re database conn
11f00 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f ections.** METHO
11f10 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
11f20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f The sqlite3_db_
11f30 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 config() interfa
11f40 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 ce is used to ma
11f50 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ke configuration
11f60 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 .** changes to a
11f70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
11f80 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 ction]. The int
11f90 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 erface is simila
11fa0 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 r to.** [sqlite3
11fb0 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 _config()] excep
11fc0 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 t that the chang
11fd0 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 es apply to a si
11fe0 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 ngle.** [databas
11ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 e connection] (s
12000 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 pecified in the
12010 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e first argument).
12020 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e .**.** The secon
12030 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 d argument to sq
12040 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
12050 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 D,V,...) is the
12060 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f .** [SQLITE_DBCO
12070 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c NFIG_LOOKASIDE |
12080 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 configuration v
12090 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 erb] - an intege
120a0 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 r code .** that
120b0 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 indicates what a
120c0 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 spect of the [da
120d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
120e0 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 n] is being conf
120f0 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 igured..** Subse
12100 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 quent arguments
12110 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f vary depending o
12120 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 n the configurat
12130 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 ion verb..**.**
12140 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 ^Calls to sqlite
12150 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 3_db_config() re
12160 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 turn SQLITE_OK i
12170 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a f and only if.**
12180 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e the call is con
12190 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 sidered successf
121a0 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ul..*/.int sqlit
121b0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c e3_db_config(sql
121c0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e ite3*, int op, .
121d0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
121e0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
121f0 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 ocation Routines
12200 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e .**.** An instan
12210 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
12220 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e t defines the in
12230 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 terface between
12240 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f SQLite.** and lo
12250 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 w-level memory a
12260 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
12270 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f es..**.** This o
12280 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e bject is used in
12290 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 only one place
122a0 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e in the SQLite in
122b0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f terface..** A po
122c0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
122d0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
122e0 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d ect is the argum
122f0 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ent to.** [sqlit
12300 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 e3_config()] whe
12310 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 n the configurat
12320 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a ion option is.**
12330 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
12340 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 MALLOC] or [SQLI
12350 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
12360 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 LOC]. .** By cr
12370 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e eating an instan
12380 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
12390 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 t.** and passing
123a0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f it to [sqlite3_
123b0 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f config]([SQLITE_
123c0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a CONFIG_MALLOC]).
123d0 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 ** during config
123e0 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c uration, an appl
123f0 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 ication can spec
12400 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 ify an alternati
12410 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c ve.** memory all
12420 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 ocation subsyste
12430 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 m for SQLite to
12440 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 use for all of i
12450 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 ts.** dynamic me
12460 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a mory needs..**.*
12470 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 * Note that SQLi
12480 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 te comes with se
12490 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 veral [built-in
124a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
124b0 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 s].** that are p
124c0 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 erfectly adequat
124d0 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 e for the overwh
124e0 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 elming majority
124f0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a of applications.
12500 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 ** and that this
12510 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 object is only
12520 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 useful to a tiny
12530 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 minority of app
12540 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 lications.** wit
12550 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 h specialized me
12560 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
12570 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 requirements. T
12580 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a his object is.**
12590 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e also used durin
125a0 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c g testing of SQL
125b0 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ite in order to
125c0 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 specify an alter
125d0 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 native.** memory
125e0 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 allocator that
125f0 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 simulates memory
12600 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 out-of-memory c
12610 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 onditions in.**
12620 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 order to verify
12630 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f that SQLite reco
12640 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 vers gracefully
12650 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e from such.** con
12660 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 ditions..**.** T
12670 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 he xMalloc, xRea
12680 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 lloc, and xFree
12690 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 methods must wor
126a0 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 k like the.** ma
126b0 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 lloc(), realloc(
126c0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e ) and free() fun
126d0 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 ctions from the
126e0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
126f0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 ry..** ^SQLite g
12700 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 uarantees that t
12710 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
12720 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f nt to.** xReallo
12730 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 c is always a va
12740 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
12750 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 a prior call to
12760 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 xRoundup..**.**
12770 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 xSize should ret
12780 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 urn the allocate
12790 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f d size of a memo
127a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ry allocation.**
127b0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 previously obta
127c0 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f ined from xMallo
127d0 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 c or xRealloc.
127e0 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 The allocated si
127f0 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 ze.** is always
12800 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 at least as big
12810 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 as the requested
12820 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 size but may be
12830 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 larger..**.** T
12840 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 he xRoundup meth
12850 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 od returns what
12860 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c would be the all
12870 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a ocated size of.*
12880 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 * a memory alloc
12890 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 ation given a pa
128a0 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 rticular request
128b0 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d ed size. Most m
128c0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
128d0 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d ors round up mem
128e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 ory allocations
128f0 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 at least to the
12900 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a next multiple.**
12910 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c of 8. Some all
12920 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 ocators round up
12930 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c to a larger mul
12940 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f tiple or to a po
12950 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 wer of 2..** Eve
12960 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ry memory alloca
12970 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d tion request com
12980 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b ing in through [
12990 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
129a0 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ].** or [sqlite3
129b0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 _realloc()] firs
129c0 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 t calls xRoundup
129d0 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 . If xRoundup r
129e0 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 eturns 0, .** th
129f0 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f at causes the co
12a00 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f rresponding memo
12a10 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f ry allocation to
12a20 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 fail..**.** The
12a30 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e xInit method in
12a40 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 itializes the me
12a50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 mory allocator.
12a60 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a For example,.**
12a70 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 it might alloca
12a80 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d te any require m
12a90 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 utexes or initia
12aa0 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 lize internal da
12ab0 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 ta.** structures
12ac0 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e . The xShutdown
12ad0 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b method is invok
12ae0 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 ed (indirectly)
12af0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 by.** [sqlite3_s
12b00 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 hutdown()] and s
12b10 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 hould deallocate
12b20 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 any resources a
12b30 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 cquired.** by xI
12b40 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 nit. The pAppDa
12b50 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 ta pointer is us
12b60 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 ed as the only p
12b70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 arameter to.** x
12b80 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f Init and xShutdo
12b90 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 wn..**.** SQLite
12ba0 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 holds the [SQLI
12bb0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
12bc0 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 MASTER] mutex wh
12bd0 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a en it invokes.**
12be0 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f the xInit metho
12bf0 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 d, so the xInit
12c00 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 method need not
12c10 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 be threadsafe.
12c20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e The.** xShutdown
12c30 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 method is only
12c40 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c called from [sql
12c50 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
12c60 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e so it does.** n
12c70 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 ot need to be th
12c80 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e readsafe either.
12c90 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 For all other
12ca0 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a methods, SQLite.
12cb0 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 ** holds the [SQ
12cc0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
12cd0 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 C_MEM] mutex as
12ce0 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b long as the.** [
12cf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
12d00 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 MSTATUS] configu
12d10 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
12d20 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 turned on (whic
12d30 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 h.** it is by de
12d40 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 fault) and so th
12d50 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 e methods are au
12d60 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 tomatically seri
12d70 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 alized..** Howev
12d80 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 er, if [SQLITE_C
12d90 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d ONFIG_MEMSTATUS]
12da0 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 is disabled, th
12db0 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 en the other.**
12dc0 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 methods must be
12dd0 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c threadsafe or el
12de0 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 se make their ow
12df0 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 n arrangements f
12e00 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 or.** serializat
12e10 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 ion..**.** SQLit
12e20 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 e will never inv
12e30 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 oke xInit() more
12e40 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f than once witho
12e50 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e ut an intervenin
12e60 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 g.** call to xSh
12e70 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 utdown()..*/.typ
12e80 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
12e90 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 te3_mem_methods
12ea0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
12eb0 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
12ec0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 te3_mem_methods
12ed0 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c {. void *(*xMal
12ee0 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 loc)(int);
12ef0 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c /* Memory all
12f00 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e ocation function
12f10 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 */. void (*xFr
12f20 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 ee)(void*);
12f30 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 /* Free a p
12f40 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
12f50 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 */. void *(*xRe
12f60 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 alloc)(void*,int
12f70 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e ); /* Resize an
12f80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
12f90 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f int (*xSize)(vo
12fa0 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 id*);
12fb0 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 /* Return the si
12fc0 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 ze of an allocat
12fd0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ion */. int (*x
12fe0 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 Roundup)(int);
12ff0 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 /* Round
13000 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 up request size
13010 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 to allocation s
13020 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ize */. int (*x
13030 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 Init)(void*);
13040 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 /* Initi
13050 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 alize the memory
13060 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 allocator */.
13070 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e void (*xShutdown
13080 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f )(void*); /
13090 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 * Deinitialize t
130a0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
130b0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 tor */. void *p
130c0 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 AppData;
130d0 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d /* Argum
130e0 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 ent to xInit() a
130f0 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a nd xShutdown() *
13100 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
13110 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 3REF: Configurat
13120 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b ion Options.** K
13130 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 EYWORDS: {config
13140 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a uration option}.
13150 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
13160 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 tants are the av
13170 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 ailable integer
13180 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
13190 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 tions that.** ca
131a0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 n be passed as t
131b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
131c0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 t to the [sqlite
131d0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 3_config()] inte
131e0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 rface..**.** New
131f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
13200 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 ptions may be ad
13210 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
13220 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
13230 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f ..** Existing co
13240 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
13250 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 ons might be dis
13260 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c continued. Appl
13270 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 ications.** shou
13280 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ld check the ret
13290 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 urn code from [s
132a0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
132b0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 to make sure th
132c0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 at.** the call w
132d0 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c orked. The [sql
132e0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 ite3_config()] i
132f0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 nterface will re
13300 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 turn a.** non-ze
13310 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ro [error code]
13320 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 if a discontinue
13330 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 d or unsupported
13340 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
13350 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f ption.** is invo
13360 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ked..**.** <dl>.
13370 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
13380 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d IG_SINGLETHREAD]
13390 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
133a0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
133b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
133c0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 re are no argume
133d0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
133e0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f on. ^This optio
133f0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 n sets the.** [t
13400 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 hreading mode] t
13410 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e o Single-thread.
13420 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 In other words
13430 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a , it disables.**
13440 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e all mutexing an
13450 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e d puts SQLite in
13460 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 to a mode where
13470 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 it can only be u
13480 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 sed.** by a sing
13490 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 le thread. ^If
134a0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
134b0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
134c0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
134d0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
134e0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
134f0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
13500 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 en.** it is not
13510 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e possible to chan
13520 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ge the [threadin
13530 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 g mode] from its
13540 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 default.** valu
13550 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 e of Single-thre
13560 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 ad and so [sqlit
13570 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c e3_config()] wil
13580 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 l return .** [SQ
13590 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 LITE_ERROR] if c
135a0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 alled with the S
135b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
135c0 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e GLETHREAD.** con
135d0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
135e0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b n.</dd>.**.** [[
135f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
13600 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e LTITHREAD]] <dt>
13610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
13620 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a LTITHREAD</dt>.*
13630 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 * <dd>There are
13640 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 no arguments to
13650 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 this option. ^T
13660 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 his option sets
13670 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e the.** [threadin
13680 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 g mode] to Multi
13690 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 -thread. In oth
136a0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 er words, it dis
136b0 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e ables.** mutexin
136c0 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 g on [database c
136d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b onnection] and [
136e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
136f0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 nt] objects..**
13700 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
13710 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
13720 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 or serializing a
13730 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 ccess to.** [dat
13740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
13750 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 s] and [prepared
13760 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 statements]. B
13770 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 ut other mutexes
13780 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 .** are enabled
13790 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 so that SQLite w
137a0 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 ill be safe to u
137b0 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 se in a multi-th
137c0 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f readed.** enviro
137d0 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 nment as long as
137e0 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 no two threads
137f0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 attempt to use t
13800 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 he same.** [data
13810 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
13820 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
13830 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 e. ^If SQLite i
13840 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
13850 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
13860 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
13870 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
13880 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
13890 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 tion then.** it
138a0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 is not possible
138b0 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 to set the Multi
138c0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 -thread [threadi
138d0 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 ng mode] and.**
138e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
138f0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b )] will return [
13900 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
13910 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 called with the
13920 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 .** SQLITE_CONFI
13930 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f G_MULTITHREAD co
13940 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
13950 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b on.</dd>.**.** [
13960 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
13970 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e ERIALIZED]] <dt>
13980 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
13990 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a RIALIZED</dt>.**
139a0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
139b0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
139c0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 his option. ^Th
139d0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
139e0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 he.** [threading
139f0 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c mode] to Serial
13a00 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 ized. In other w
13a10 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f ords, this optio
13a20 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c n enables.** all
13a30 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 mutexes includi
13a40 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 ng the recursive
13a50 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b .** mutexes on [
13a60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
13a70 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ion] and [prepar
13a80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 ed statement] ob
13a90 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 jects..** In thi
13aa0 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 s mode (which is
13ab0 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 the default whe
13ac0 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 n SQLite is comp
13ad0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 iled with.** [SQ
13ae0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
13af0 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 1]) the SQLite l
13b00 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 ibrary will itse
13b10 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 lf serialize acc
13b20 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 ess.** to [datab
13b30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
13b40 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
13b50 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 tatements] so th
13b60 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 at the.** applic
13b70 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f ation is free to
13b80 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 use the same [d
13b90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
13ba0 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 on] or the.** sa
13bb0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 me [prepared sta
13bc0 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 tement] in diffe
13bd0 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 rent threads at
13be0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a the same time..*
13bf0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 * ^If SQLite is
13c00 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
13c10 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
13c20 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
13c30 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
13c40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
13c50 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 on then.** it is
13c60 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f not possible to
13c70 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 set the Seriali
13c80 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d zed [threading m
13c90 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ode] and.** [sql
13ca0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
13cb0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ill return [SQLI
13cc0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c TE_ERROR] if cal
13cd0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
13ce0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
13cf0 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 RIALIZED configu
13d00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f ration option.</
13d10 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
13d20 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
13d30 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
13d40 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e NFIG_MALLOC</dt>
13d50 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 .** <dd> ^(The S
13d60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
13d70 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 LOC option takes
13d80 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
13d90 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 nt which is .**
13da0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
13db0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
13dc0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
13dd0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
13de0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 .** The argument
13df0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c specifies.** al
13e00 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 ternative low-le
13e10 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 vel memory alloc
13e20 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 ation routines t
13e30 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 o be used in pla
13e40 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d ce of.** the mem
13e50 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
13e60 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e outines built in
13e70 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 to SQLite.)^ ^SQ
13e80 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 Lite makes.** it
13e90 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f s own private co
13ea0 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e py of the conten
13eb0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 t of the [sqlite
13ec0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 3_mem_methods] s
13ed0 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f tructure.** befo
13ee0 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f re the [sqlite3_
13ef0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 config()] call r
13f00 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a eturns.</dd>.**.
13f10 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
13f20 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c IG_GETMALLOC]] <
13f30 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
13f40 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a _GETMALLOC</dt>.
13f50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
13f60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
13f70 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b ALLOC option tak
13f80 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
13f90 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 ment which.** is
13fa0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
13fb0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
13fc0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
13fd0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
13fe0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 ..** The [sqlite
13ff0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 3_mem_methods].*
14000 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 * structure is f
14010 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 illed with the c
14020 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
14030 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
14040 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a on routines.)^.*
14050 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 * This option ca
14060 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 n be used to ove
14070 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c rload the defaul
14080 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
14090 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ion.** routines
140a0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 with a wrapper t
140b0 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 hat simulations
140c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
140d0 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 n failure or.**
140e0 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 tracks memory us
140f0 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 age, for example
14100 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b . </dd>.**.** [[
14110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d SQLITE_CONFIG_SM
14120 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 ALL_MALLOC]] <dt
14130 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
14140 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e MALL_MALLOC</dt>
14150 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 .** <dd> ^The SQ
14160 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c LITE_CONFIG_SMAL
14170 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 L_MALLOC option
14180 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 takes single arg
14190 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65 ument of.** type
141a0 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 int, interprete
141b0 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 d as a boolean,
141c0 77 68 69 63 68 20 69 66 20 74 72 75 65 20 70 72 which if true pr
141d0 6f 76 69 64 65 73 20 61 20 68 69 6e 74 20 74 6f ovides a hint to
141e0 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68 61 74 20 .** SQLite that
141f0 69 74 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 it should avoid
14200 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c large memory all
14210 6f 63 61 74 69 6f 6e 73 20 69 66 20 70 6f 73 73 ocations if poss
14220 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 ible..** SQLite
14230 77 69 6c 6c 20 72 75 6e 20 66 61 73 74 65 72 20 will run faster
14240 69 66 20 69 74 20 69 73 20 66 72 65 65 20 74 6f if it is free to
14250 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f make large memo
14260 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a ry allocations,.
14270 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61 70 70 6c ** but some appl
14280 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 70 72 ication might pr
14290 65 66 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77 efer to run slow
142a0 65 72 20 69 6e 20 65 78 63 68 61 6e 67 65 20 66 er in exchange f
142b0 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 or.** guarantees
142c0 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72 about memory fr
142d0 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 agmentation that
142e0 20 61 72 65 20 70 6f 73 73 69 62 6c 65 20 69 66 are possible if
142f0 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 large.** alloca
14300 74 69 6f 6e 73 20 61 72 65 20 61 76 6f 69 64 65 tions are avoide
14310 64 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 d. This hint is
14320 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a normally off..*
14330 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b * </dd>.**.** [[
14340 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
14350 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 MSTATUS]] <dt>SQ
14360 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
14370 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 TATUS</dt>.** <d
14380 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 d> ^The SQLITE_C
14390 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 ONFIG_MEMSTATUS
143a0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e option takes sin
143b0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 gle argument of
143c0 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 type int,.** int
143d0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f erpreted as a bo
143e0 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 olean, which ena
143f0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 bles or disables
14400 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 the collection
14410 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c of.** memory all
14420 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 ocation statisti
14430 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 cs. ^(When memor
14440 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 y allocation sta
14450 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 tistics are.** d
14460 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c isabled, the fol
14470 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e lowing SQLite in
14480 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 terfaces become
14490 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a non-operational:
144a0 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 .** <ul>.**
144b0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 <li> [sqlite3_me
144c0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 mory_used()].**
144d0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
144e0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
144f0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
14500 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 qlite3_soft_heap
14510 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 _limit64()].**
14520 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 <li> [sqlite3_s
14530 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 tatus64()].**
14540 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f </ul>)^.** ^Memo
14550 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 ry allocation st
14560 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 atistics are ena
14570 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 bled by default
14580 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 unless SQLite is
14590 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 .** compiled wit
145a0 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c h [SQLITE_DEFAUL
145b0 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 T_MEMSTATUS]=0 i
145c0 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d n which case mem
145d0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f ory.** allocatio
145e0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 n statistics are
145f0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
14600 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a ault..** </dd>.*
14610 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
14620 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c NFIG_SCRATCH]] <
14630 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
14640 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a _SCRATCH</dt>.**
14650 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 <dd> The SQLITE
14660 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 _CONFIG_SCRATCH
14670 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e option is no lon
14680 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 ger used..** </d
14690 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
146a0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
146b0 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f HE]] <dt>SQLITE_
146c0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
146d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
146e0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
146f0 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f _PAGECACHE optio
14700 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 n specifies a me
14710 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 mory pool.** tha
14720 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 t SQLite can use
14730 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 for the databas
14740 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 e page cache wit
14750 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 h the default pa
14760 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c ge.** cache impl
14770 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a ementation. .**
14780 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 This configurat
14790 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 ion option is a
147a0 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c no-op if an appl
147b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 ication-define p
147c0 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 age.** cache imp
147d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c lementation is l
147e0 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 oaded using the
147f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
14800 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 CACHE2]..** ^The
14810 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
14820 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 uments to SQLITE
14830 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
14840 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a E: A pointer to.
14850 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 ** 8-byte aligne
14860 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c d memory (pMem),
14870 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 the size of eac
14880 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e h page cache lin
14890 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 e (sz),.** and t
148a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 he number of cac
148b0 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a he lines (N)..**
148c0 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 The sz argument
148d0 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 should be the s
148e0 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 ize of the large
148f0 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 st database page
14900 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 .** (a power of
14910 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 two between 512
14920 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 and 65536) plus
14930 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 some extra bytes
14940 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 for each.** pag
14950 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 e header. ^The
14960 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 number of extra
14970 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 bytes needed by
14980 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a the page header.
14990 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d ** can be determ
149a0 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 ined using [SQLI
149b0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
149c0 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 _HDRSZ]..** ^It
149d0 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 is harmless, apa
149e0 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 rt from the wast
149f0 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f ed memory,.** fo
14a00 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 r the sz paramet
14a10 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 er to be larger
14a20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 than necessary.
14a30 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 The pMem.** arg
14a40 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 ument must be ei
14a50 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e ther a NULL poin
14a60 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 ter or a pointer
14a70 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a to an 8-byte.**
14a80 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f aligned block o
14a90 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c f memory of at l
14aa0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c east sz*N bytes,
14ab0 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 otherwise.** su
14ac0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f bsequent behavio
14ad0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a r is undefined..
14ae0 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 ** ^When pMem is
14af0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 not NULL, SQLit
14b00 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f e will strive to
14b10 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 use the memory
14b20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 provided.** to s
14b30 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68 atisfy page cach
14b40 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 e needs, falling
14b50 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 back to [sqlite
14b60 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 3_malloc()] if.*
14b70 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c * a page cache l
14b80 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 ine is larger th
14b90 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 an sz bytes or i
14ba0 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 f all of the pMe
14bb0 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 m buffer.** is e
14bc0 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 xhausted..** ^If
14bd0 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e pMem is NULL an
14be0 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c d N is non-zero,
14bf0 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 then each datab
14c00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
14c10 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 * does an initia
14c20 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f l bulk allocatio
14c30 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 n for page cache
14c40 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 memory.** from
14c50 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
14c60 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f )] sufficient fo
14c70 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 r N cache lines
14c80 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 if N is positive
14c90 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a or.** of -1024*
14ca0 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 N bytes if N is
14cb0 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 negative, . ^If
14cc0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 additional.** pa
14cd0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 ge cache memory
14ce0 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 is needed beyond
14cf0 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 what is provide
14d00 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c d by the initial
14d10 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 .** allocation,
14d20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 then SQLite goes
14d30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c to [sqlite3_mal
14d40 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c loc()] separatel
14d50 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 y for each.** ad
14d60 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c ditional cache l
14d70 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ine. </dd>.**.**
14d80 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
14d90 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 _HEAP]] <dt>SQLI
14da0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f TE_CONFIG_HEAP</
14db0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 dt>.** <dd> ^The
14dc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 SQLITE_CONFIG_H
14dd0 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 EAP option speci
14de0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
14df0 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 mory buffer .**
14e00 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c that SQLite will
14e10 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 use for all of
14e20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f its dynamic memo
14e30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
14e40 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 eds.** beyond th
14e50 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 ose provided for
14e60 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 by [SQLITE_CONF
14e70 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a IG_PAGECACHE]..*
14e80 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f * ^The SQLITE_CO
14e90 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e NFIG_HEAP option
14ea0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 is only availab
14eb0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 le if SQLite is
14ec0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 compiled.** with
14ed0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f either [SQLITE_
14ee0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 ENABLE_MEMSYS3]
14ef0 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c or [SQLITE_ENABL
14f00 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 E_MEMSYS5] and r
14f10 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 eturns.** [SQLIT
14f20 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f E_ERROR] if invo
14f30 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a ked otherwise..*
14f40 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 * ^There are thr
14f50 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 ee arguments to
14f60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 SQLITE_CONFIG_HE
14f70 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 AP:.** An 8-byte
14f80 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 aligned pointer
14f90 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a to the memory,.
14fa0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
14fb0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 bytes in the me
14fc0 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 mory buffer, and
14fd0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c the minimum all
14fe0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a ocation size..**
14ff0 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 ^If the first p
15000 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f ointer (the memo
15010 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e ry pointer) is N
15020 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ULL, then SQLite
15030 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 reverts.** to u
15040 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 sing its default
15050 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
15060 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 r (the system ma
15070 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 lloc() implement
15080 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 ation),.** undoi
15090 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 ng any prior inv
150a0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 ocation of [SQLI
150b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
150c0 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d ]. ^If the.** m
150d0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 emory pointer is
150e0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 not NULL then t
150f0 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d he alternative m
15100 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
15110 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f or is engaged to
15120 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 handle all of S
15130 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c QLites memory al
15140 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a location needs..
15150 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 ** The first poi
15160 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 nter (the memory
15170 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 pointer) must b
15180 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
15190 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 8-byte.** bounda
151a0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 ry or subsequent
151b0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c behavior of SQL
151c0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 ite will be unde
151d0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 fined..** The mi
151e0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
151f0 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 size is capped
15200 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e at 2**12. Reason
15210 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 able values.** f
15220 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 or the minimum a
15230 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 llocation size a
15240 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 re 2**5 through
15250 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 2**8.</dd>.**.**
15260 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
15270 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c _MUTEX]] <dt>SQL
15280 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
15290 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
152a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
152b0 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 G_MUTEX option t
152c0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
152d0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
152e0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 a.** pointer to
152f0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
15300 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
15310 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 x_methods] struc
15320 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 ture..** The arg
15330 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 ument specifies
15340 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d alternative low-
15350 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 level mutex rout
15360 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a ines to be used.
15370 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 ** in place the
15380 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 mutex routines b
15390 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 uilt into SQLite
153a0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b .)^ ^SQLite mak
153b0 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 es a copy of.**
153c0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
153d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
153e0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 x_methods] struc
153f0 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 ture before the
15400 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
15410 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 te3_config()] re
15420 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 turns. ^If SQLit
15430 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
15440 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 th.** the [SQLIT
15450 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 E_THREADSAFE | S
15460 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
15470 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =0] compile-time
15480 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 option then.**
15490 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 the entire mutex
154a0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 ing subsystem is
154b0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 omitted from th
154c0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 e build and henc
154d0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 e calls to.** [s
154e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
154f0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 with the SQLITE
15500 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f _CONFIG_MUTEX co
15510 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
15520 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 on will.** retur
15530 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d n [SQLITE_ERROR]
15540 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
15550 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
15560 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 MUTEX]] <dt>SQLI
15570 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
15580 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 EX</dt>.** <dd>
15590 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^(The SQLITE_CON
155a0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 FIG_GETMUTEX opt
155b0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
155c0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
155d0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 h.** is a pointe
155e0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 r to an instance
155f0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
15600 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 _mutex_methods]
15610 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a structure. The.
15620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 ** [sqlite3_mute
15630 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 x_methods].** st
15640 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 ructure is fille
15650 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 d with the curre
15660 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 ntly defined mut
15670 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a ex routines.)^.*
15680 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 * This option ca
15690 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 n be used to ove
156a0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c rload the defaul
156b0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 t mutex allocati
156c0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 on.** routines w
156d0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 ith a wrapper us
156e0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 ed to track mute
156f0 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 x usage for perf
15700 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 ormance.** profi
15710 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c ling or testing,
15720 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 for example.
15730 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
15740 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
15750 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
15760 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
15770 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
15780 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
15790 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 then.** the ent
157a0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 ire mutexing sub
157b0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 system is omitte
157c0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 d from the build
157d0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 and hence calls
157e0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
157f0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 config()] with t
15800 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
15810 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 _GETMUTEX config
15820 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 uration option w
15830 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 ill.** return [S
15840 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 QLITE_ERROR].</d
15850 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
15860 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
15870 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f DE]] <dt>SQLITE_
15880 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
15890 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
158a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
158b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 G_LOOKASIDE opti
158c0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 on takes two arg
158d0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 uments that dete
158e0 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 rmine.** the def
158f0 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f ault size of loo
15900 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e kaside memory on
15910 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 each [database
15920 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 connection]..**
15930 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
15940 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a nt is the.** siz
15950 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 e of each lookas
15960 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 ide buffer slot
15970 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 and the second i
15980 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a s the number of.
15990 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 ** slots allocat
159a0 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 ed to each datab
159b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 ase connection.)
159c0 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 ^ ^(SQLITE_CONF
159d0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 IG_LOOKASIDE.**
159e0 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 sets the <i>defa
159f0 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 ult</i> lookasid
15a00 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c e size. The [SQL
15a10 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
15a20 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f KASIDE].** optio
15a30 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 n to [sqlite3_db
15a40 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 _config()] can b
15a50 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 e used to change
15a60 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a the lookaside.*
15a70 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 * configuration
15a80 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f on individual co
15a90 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 nnections.)^ </d
15aa0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
15ab0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 E_CONFIG_PCACHE2
15ac0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
15ad0 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 NFIG_PCACHE2</dt
15ae0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 >.** <dd> ^(The
15af0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
15b00 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b ACHE2 option tak
15b10 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
15b20 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a ment which is .*
15b30 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * a pointer to a
15b40 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 n [sqlite3_pcach
15b50 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 e_methods2] obje
15b60 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 ct. This object
15b70 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 specifies.** th
15b80 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 e interface to a
15b90 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 custom page cac
15ba0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
15bb0 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 n.)^.** ^SQLite
15bc0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
15bd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 the [sqlite3_pca
15be0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 che_methods2] ob
15bf0 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ject.</dd>.**.**
15c00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
15c10 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 _GETPCACHE2]] <d
15c20 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
15c30 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a GETPCACHE2</dt>.
15c40 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
15c50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
15c60 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 CACHE2 option ta
15c70 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
15c80 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 ument which.** i
15c90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
15ca0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 n [sqlite3_pcach
15cb0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 e_methods2] obje
15cc0 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 ct. SQLite copi
15cd0 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 es of.** the cur
15ce0 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 rent page cache
15cf0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
15d00 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e nto that object.
15d10 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b )^ </dd>.**.** [
15d20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c [SQLITE_CONFIG_L
15d30 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f OG]] <dt>SQLITE_
15d40 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a CONFIG_LOG</dt>.
15d50 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 ** <dd> The SQLI
15d60 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 TE_CONFIG_LOG op
15d70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
15d80 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 configure the SQ
15d90 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b Lite.** global [
15da0 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 error log]..** (
15db0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
15dc0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 IG_LOG option ta
15dd0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 kes two argument
15de0 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 s: a pointer to
15df0 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 a.** function wi
15e00 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 th a call signat
15e10 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 ure of void(*)(v
15e20 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 oid*,int,const c
15e30 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 har*), .** and a
15e40 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 pointer to void
15e50 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 . ^If the functi
15e60 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f on pointer is no
15e70 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a t NULL, it is.**
15e80 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c invoked by [sql
15e90 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 ite3_log()] to p
15ea0 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 rocess each logg
15eb0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 ing event. ^If
15ec0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 the.** function
15ed0 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c pointer is NULL,
15ee0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f the [sqlite3_lo
15ef0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 g()] interface b
15f00 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a ecomes a no-op..
15f10 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 ** ^The void poi
15f20 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 nter that is the
15f30 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
15f40 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 to SQLITE_CONFI
15f50 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 G_LOG is.** pass
15f60 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 ed through as th
15f70 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
15f80 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 r to the applica
15f90 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 tion-defined log
15fa0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ger.** function
15fb0 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 whenever that fu
15fc0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 nction is invoke
15fd0 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 d. ^The second
15fe0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
15ff0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 the logger funct
16000 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ion is a copy of
16010 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
16020 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 eter to the corr
16030 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 esponding.** [sq
16040 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c lite3_log()] cal
16050 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 l and is intende
16060 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c d to be a [resul
16070 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a t code] or an.**
16080 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
16090 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 t code]. ^The t
160a0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 hird parameter p
160b0 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 assed to the log
160c0 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 ger is.** log me
160d0 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d ssage after form
160e0 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 atting via [sqli
160f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e te3_snprintf()].
16100 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c .** The SQLite l
16110 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 ogging interface
16120 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e is not reentran
16130 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 t; the logger fu
16140 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 nction.** suppli
16150 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ed by the applic
16160 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 ation must not i
16170 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 nvoke any SQLite
16180 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 interface..** I
16190 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 n a multi-thread
161a0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 ed application,
161b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
161c0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a defined logger.*
161d0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 * function must
161e0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c be threadsafe. <
161f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
16200 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d ITE_CONFIG_URI]]
16210 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
16220 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 IG_URI.** <dd>^(
16230 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
16240 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b G_URI option tak
16250 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
16260 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 ment of type int
16270 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f ..** If non-zero
16280 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c , then URI handl
16290 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 ing is globally
162a0 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 enabled. If the
162b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 parameter is zer
162c0 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 o,.** then URI h
162d0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 andling is globa
162e0 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 lly disabled.)^
162f0 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 ^If URI handling
16300 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 is globally.**
16310 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c enabled, all fil
16320 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f enames passed to
16330 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
16340 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
16350 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 _v2()],.** [sqli
16360 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 te3_open16()] or
16370 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 .** specified as
16380 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 part of [ATTACH
16390 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 ] commands are i
163a0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 nterpreted as UR
163b0 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a Is, regardless.*
163c0 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 * of whether or
163d0 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f not the [SQLITE_
163e0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 OPEN_URI] flag i
163f0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 s set when the d
16400 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
16410 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e ction is opened.
16420 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 ^If it is globa
16430 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 lly disabled, fi
16440 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f lenames are.** o
16450 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 nly interpreted
16460 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 as URIs if the S
16470 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 QLITE_OPEN_URI f
16480 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 lag is set when
16490 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
164a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 connection is op
164b0 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 ened. ^(By defau
164c0 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 lt, URI handling
164d0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 is globally.**
164e0 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 disabled. The de
164f0 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 fault value may
16500 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f be changed by co
16510 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 mpiling with the
16520 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f .** [SQLITE_USE_
16530 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 URI] symbol defi
16540 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 ned.)^.**.** [[S
16550 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 QLITE_CONFIG_COV
16560 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e ERING_INDEX_SCAN
16570 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
16580 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e NFIG_COVERING_IN
16590 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e DEX_SCAN.** <dd>
165a0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
165b0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 IG_COVERING_INDE
165c0 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 X_SCAN option ta
165d0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 kes a single int
165e0 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 eger.** argument
165f0 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 which is interp
16600 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 reted as a boole
16610 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 an in order to e
16620 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 nable or disable
16630 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 .** the use of c
16640 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 overing indices
16650 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 for full table s
16660 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 cans in the quer
16670 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 y optimizer..**
16680 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 ^The default set
16690 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e ting is determin
166a0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 ed.** by the [SQ
166b0 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 LITE_ALLOW_COVER
166c0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 ING_INDEX_SCAN]
166d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
166e0 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a ion, or is "on".
166f0 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 ** if that compi
16700 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 le-time option i
16710 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 s omitted..** Th
16720 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 e ability to dis
16730 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 able the use of
16740 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 covering indices
16750 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 for full table
16760 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 scans.** is beca
16770 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 use some incorre
16780 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 ctly coded legac
16790 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d y applications m
167a0 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e ight malfunction
167b0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 .** when the opt
167c0 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 imization is ena
167d0 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 bled. Providing
167e0 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a the ability to.
167f0 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f ** disable the o
16800 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f ptimization allo
16810 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 ws the older, bu
16820 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 ggy application
16830 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 code to work.**
16840 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 without change e
16850 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 ven with newer v
16860 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
16870 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 e..**.** [[SQLIT
16880 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d E_CONFIG_PCACHE]
16890 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ] [[SQLITE_CONFI
168a0 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a G_GETPCACHE]].**
168b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
168c0 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 IG_PCACHE and SQ
168d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
168e0 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 CACHE.** <dd> Th
168f0 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 ese options are
16900 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f obsolete and sho
16910 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 uld not be used
16920 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 by new code..**
16930 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 They are retaine
16940 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 d for backwards
16950 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 compatibility bu
16960 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 t are now no-ops
16970 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ..** </dd>.**.**
16980 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
16990 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 _SQLLOG]].** <dt
169a0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
169b0 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 QLLOG.** <dd>Thi
169c0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 s option is only
169d0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 available if sq
169e0 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 lite is compiled
169f0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 with the.** [SQ
16a00 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c LITE_ENABLE_SQLL
16a10 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f OG] pre-processo
16a20 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e r macro defined.
16a30 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
16a40 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 ent should.** be
16a50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
16a60 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 function of type
16a70 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 void(*)(void*,s
16a80 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 qlite3*,const ch
16a90 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 ar*, int)..** Th
16aa0 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 e second should
16ab0 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 be of type (void
16ac0 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b *). The callback
16ad0 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 is invoked by t
16ae0 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e he library.** in
16af0 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 three separate
16b00 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 circumstances, i
16b10 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 dentified by the
16b20 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 value passed as
16b30 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 the.** fourth p
16b40 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 arameter. If the
16b50 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
16b60 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 r is 0, then the
16b70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
16b80 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 tion.** passed a
16b90 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
16ba0 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 ument has just b
16bb0 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 een opened. The
16bc0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a third argument.*
16bd0 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 * points to a bu
16be0 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 ffer containing
16bf0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
16c00 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 main database fi
16c10 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f le. If the.** fo
16c20 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
16c30 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 s 1, then the SQ
16c40 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 L statement that
16c50 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
16c60 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 eter.** points t
16c70 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 o has just been
16c80 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 executed. Or, if
16c90 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
16ca0 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e meter is 2, then
16cb0 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 .** the connecti
16cc0 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 on being passed
16cd0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
16ce0 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 rameter is being
16cf0 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 closed. The.**
16d00 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
16d10 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 is passed NULL I
16d20 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e n this case. An
16d30 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e example of usin
16d40 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 g this.** config
16d50 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 uration option c
16d60 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 an be seen in th
16d70 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 e "test_sqllog.c
16d80 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e " source file in
16d90 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 .** the canonica
16da0 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 l SQLite source
16db0 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tree.</dd>.**.**
16dc0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
16dd0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 _MMAP_SIZE]].**
16de0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
16df0 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c G_MMAP_SIZE.** <
16e00 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 dd>^SQLITE_CONFI
16e10 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 G_MMAP_SIZE take
16e20 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 s two 64-bit int
16e30 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e eger (sqlite3_in
16e40 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 t64) values.** t
16e50 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 hat are the defa
16e60 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 ult mmap size li
16e70 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 mit (the default
16e80 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 setting for.**
16e90 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a [PRAGMA mmap_siz
16ea0 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 e]) and the maxi
16eb0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 mum allowed mmap
16ec0 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 size limit..**
16ed0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 ^The default set
16ee0 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 ting can be over
16ef0 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 ridden by each d
16f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
16f10 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 on using.** eith
16f20 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d er the [PRAGMA m
16f30 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e map_size] comman
16f40 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 d, or by using t
16f50 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 he.** [SQLITE_FC
16f60 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 NTL_MMAP_SIZE] f
16f70 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 ile control. ^(
16f80 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f The maximum allo
16f90 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a wed mmap size.**
16fa0 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c will be silentl
16fb0 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e y truncated if n
16fc0 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 ecessary so that
16fd0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 it does not exc
16fe0 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 eed the.** compi
16ff0 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 le-time maximum
17000 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 mmap size set by
17010 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
17020 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 MAX_MMAP_SIZE] c
17030 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
17040 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 on.)^.** ^If eit
17050 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 her argument to
17060 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e this option is n
17070 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 egative, then th
17080 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a at argument is.*
17090 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 * changed to its
170a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 compile-time de
170b0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 fault..**.** [[S
170c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e QLITE_CONFIG_WIN
170d0 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 32_HEAPSIZE]].**
170e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
170f0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a IG_WIN32_HEAPSIZ
17100 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 E.** <dd>^The SQ
17110 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 LITE_CONFIG_WIN3
17120 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 2_HEAPSIZE optio
17130 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 n is only availa
17140 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 ble if SQLite is
17150 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 .** compiled for
17160 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 Windows with th
17170 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f e [SQLITE_WIN32_
17180 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 MALLOC] pre-proc
17190 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 essor macro.** d
171a0 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f efined. ^SQLITE_
171b0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 CONFIG_WIN32_HEA
171c0 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 PSIZE takes a 32
171d0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e -bit unsigned in
171e0 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 teger value.** t
171f0 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 hat specifies th
17200 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f e maximum size o
17210 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 f the created he
17220 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 ap..**.** [[SQLI
17230 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
17240 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e _HDRSZ]].** <dt>
17250 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
17260 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 ACHE_HDRSZ.** <d
17270 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f d>^The SQLITE_CO
17280 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 NFIG_PCACHE_HDRS
17290 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 Z option takes a
172a0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 single paramete
172b0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 r which.** is a
172c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
172d0 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 teger and writes
172e0 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 into that integ
172f0 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 er the number of
17300 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 extra.** bytes
17310 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 per page require
17320 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 d for each page
17330 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 in [SQLITE_CONFI
17340 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a G_PAGECACHE]..**
17350 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 The amount of e
17360 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 xtra space requi
17370 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 red can change d
17380 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
17390 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 compiler,.** tar
173a0 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e get platform, an
173b0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e d SQLite version
173c0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ..**.** [[SQLITE
173d0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a _CONFIG_PMASZ]].
173e0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
173f0 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 NFIG_PMASZ.** <d
17400 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f d>^The SQLITE_CO
17410 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f NFIG_PMASZ optio
17420 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
17430 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 parameter which
17440 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e .** is an unsign
17450 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 ed integer and s
17460 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d ets the "Minimum
17470 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 PMA Size" for t
17480 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 he multithreaded
17490 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 .** sorter to th
174a0 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 at integer. The
174b0 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d default minimum
174c0 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 PMA Size is set
174d0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 by the.** [SQLI
174e0 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d TE_SORTER_PMASZ]
174f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
17500 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 tion. New threa
17510 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a ds are launched.
17520 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 ** to help with
17530 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 sort operations
17540 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 when multithread
17550 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 ed sorting.** is
17560 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 enabled (using
17570 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 the [PRAGMA thre
17580 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e ads] command) an
17590 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 d the amount of
175a0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 content.** to be
175b0 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 sorted exceeds
175c0 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 the page size ti
175d0 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 mes the minimum
175e0 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d of the.** [PRAGM
175f0 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 A cache_size] se
17600 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 tting and this v
17610 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 alue..**.** [[SQ
17620 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 LITE_CONFIG_STMT
17630 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 JRNL_SPILL]].**
17640 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
17650 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c G_STMTJRNL_SPILL
17660 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c .** <dd>^The SQL
17670 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a ITE_CONFIG_STMTJ
17680 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e RNL_SPILL option
17690 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
176a0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a parameter which.
176b0 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b ** becomes the [
176c0 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 statement journa
176d0 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b l] spill-to-disk
176e0 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a threshold. .**
176f0 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 [Statement jour
17700 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69 nals] are held i
17710 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 n memory until t
17720 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79 heir size (in by
17730 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 tes).** exceeds
17740 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 this threshold,
17750 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74 at which point t
17760 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20 hey are written
17770 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 to disk..** Or i
17780 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20 f the threshold
17790 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 is -1, statement
177a0 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c journals are al
177b0 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 ways held.** exc
177c0 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f lusively in memo
177d0 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e ry..** Since man
177e0 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 y statement jour
177f0 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d nals never becom
17800 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67 e large, setting
17810 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 the spill.** th
17820 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c reshold to a val
17830 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42 ue such as 64KiB
17840 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64 can greatly red
17850 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f uce the amount o
17860 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 f.** I/O require
17870 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61 d to support sta
17880 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e tement rollback.
17890 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 .** The default
178a0 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73 value for this s
178b0 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f etting is contro
178c0 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b lled by the.** [
178d0 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f SQLITE_STMTJRNL_
178e0 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 SPILL] compile-t
178f0 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c ime option..** <
17900 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
17910 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
17920 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f NGLETHREAD 1 /
17930 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 * nil */.#define
17940 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
17950 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 ULTITHREAD 2
17960 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
17970 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
17980 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 SERIALIZED 3
17990 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
179a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
179b0 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 _MALLOC 4
179c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d /* sqlite3_mem
179d0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
179e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
179f0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 IG_GETMALLOC
17a00 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 5 /* sqlite3_m
17a10 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 em_methods* */.#
17a20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
17a30 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 NFIG_SCRATCH
17a40 20 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 6 /* No long
17a50 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 er used */.#defi
17a60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
17a70 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 _PAGECACHE 7
17a80 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
17a90 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 sz, int N */.#de
17aa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
17ab0 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 IG_HEAP
17ac0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 8 /* void*, in
17ad0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e t nByte, int min
17ae0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17af0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
17b00 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f TUS 9 /* bo
17b10 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 olean */.#define
17b20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
17b30 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 UTEX 10
17b40 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 /* sqlite3_mutex
17b50 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
17b60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
17b70 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 IG_GETMUTEX
17b80 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 11 /* sqlite3_m
17b90 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f utex_methods* */
17ba0 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 ./* previously S
17bb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 QLITE_CONFIG_CHU
17bc0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 NKALLOC 12 which
17bd0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 is now unused.
17be0 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */ .#define SQLI
17bf0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 TE_CONFIG_LOOKAS
17c00 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e IDE 13 /* in
17c10 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 t int */.#define
17c20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
17c30 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 CACHE 14
17c40 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 /* no-op */.#def
17c50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
17c60 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 G_GETPCACHE 1
17c70 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 5 /* no-op */.#
17c80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
17c90 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 NFIG_LOG
17ca0 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 16 /* xFunc,
17cb0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 void* */.#define
17cc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 SQLITE_CONFIG_U
17cd0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 RI 17
17ce0 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e /* int */.#defin
17cf0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
17d00 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 PCACHE2 18
17d10 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 /* sqlite3_pcac
17d20 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a he_methods2* */.
17d30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
17d40 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 ONFIG_GETPCACHE2
17d50 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 19 /* sqlite
17d60 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
17d70 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 2* */.#define SQ
17d80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 LITE_CONFIG_COVE
17d90 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 RING_INDEX_SCAN
17da0 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 20 /* int */.#d
17db0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
17dc0 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 FIG_SQLLOG
17dd0 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 21 /* xSqllog,
17de0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e void* */.#defin
17df0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
17e00 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 MMAP_SIZE 22
17e10 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 /* sqlite3_int6
17e20 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 4, sqlite3_int64
17e30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17e40 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f TE_CONFIG_WIN32_
17e50 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 HEAPSIZE 23
17e60 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a /* int nByte *
17e70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17e80 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 _CONFIG_PCACHE_H
17e90 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 DRSZ 24
17ea0 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 /* int *psz */.#
17eb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
17ec0 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 NFIG_PMASZ
17ed0 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 25 /*
17ee0 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 unsigned int szP
17ef0 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ma */.#define SQ
17f00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 LITE_CONFIG_STMT
17f10 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 JRNL_SPILL
17f20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 26 /* int nByte
17f30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17f40 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f TE_CONFIG_SMALL_
17f50 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37 MALLOC 27
17f60 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a /* boolean */.
17f70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
17f80 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
17f90 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 tion Configurati
17fa0 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a on Options.**.**
17fb0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
17fc0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 are the availab
17fd0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 le integer confi
17fe0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
17ff0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 that.** can be
18000 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 passed as the se
18010 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
18020 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 the [sqlite3_db
18030 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
18040 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 face..**.** New
18050 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
18060 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 tions may be add
18070 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
18080 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e eases of SQLite.
18090 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e .** Existing con
180a0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
180b0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 ns might be disc
180c0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 ontinued. Appli
180d0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c cations.** shoul
180e0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 d check the retu
180f0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 rn code from [sq
18100 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
18110 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 )] to make sure
18120 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c that.** the call
18130 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b worked. ^The [
18140 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
18150 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 g()] interface w
18160 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 ill return a.**
18170 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 non-zero [error
18180 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f code] if a disco
18190 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 ntinued or unsup
181a0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 ported configura
181b0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 tion option.** i
181c0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a s invoked..**.**
181d0 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c <dl>.** <dt>SQL
181e0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
181f0 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c KASIDE</dt>.** <
18200 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
18210 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 takes three add
18220 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
18230 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 s that determine
18240 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 the .** [lookas
18250 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ide memory alloc
18260 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 ator] configurat
18270 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 ion for the [dat
18280 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
18290 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 ]..** ^The first
182a0 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 argument (the t
182b0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
182c0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f o [sqlite3_db_co
182d0 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 nfig()] is a.**
182e0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d pointer to a mem
182f0 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 ory buffer to us
18300 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 e for lookaside
18310 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 memory..** ^The
18320 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 first argument a
18330 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f fter the SQLITE_
18340 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
18350 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 DE verb.** may b
18360 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 e NULL in which
18370 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c case SQLite will
18380 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a allocate the.**
18390 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 lookaside buffe
183a0 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b r itself using [
183b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
183c0 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 ]. ^The second a
183d0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a rgument is the.*
183e0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c * size of each l
183f0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 ookaside buffer
18400 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 slot. ^The thir
18410 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
18420 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 e number of.** s
18430 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 lots. The size
18440 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e of the buffer in
18450 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
18460 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 ent must be grea
18470 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 ter than.** or e
18480 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 qual to the prod
18490 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e uct of the secon
184a0 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 d and third argu
184b0 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 ments. The buff
184c0 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c er.** must be al
184d0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 igned to an 8-by
184e0 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 te boundary. ^I
184f0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 f the second arg
18500 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 ument to.** SQLI
18510 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
18520 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d ASIDE is not a m
18530 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 ultiple of 8, it
18540 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a is internally.*
18550 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 * rounded down t
18560 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c o the next small
18570 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 er multiple of 8
18580 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 . ^(The lookasi
18590 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e de memory.** con
185a0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 figuration for a
185b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
185c0 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 tion can only be
185d0 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 changed when th
185e0 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e at.** connection
185f0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c is not currentl
18600 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 y using lookasid
18610 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 e memory, or in
18620 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 other words.** w
18630 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 hen the "current
18640 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 value" returned
18650 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f by.** [sqlite3_
18660 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 db_status](D,[SQ
18670 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
18680 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a ASIDE],...) is z
18690 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 ero..** Any atte
186a0 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 mpt to change th
186b0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f e lookaside memo
186c0 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ry configuration
186d0 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a when lookaside.
186e0 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 ** memory is in
186f0 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 use leaves the c
18700 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 onfiguration unc
18710 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 hanged and retur
18720 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 ns .** [SQLITE_B
18730 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a USY].)^</dd>.**.
18740 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 ** <dt>SQLITE_DB
18750 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b CONFIG_ENABLE_FK
18760 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 EY</dt>.** <dd>
18770 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 ^This option is
18780 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f used to enable o
18790 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e r disable the en
187a0 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 forcement of.**
187b0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e [foreign key con
187c0 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 straints]. Ther
187d0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 e should be two
187e0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d additional argum
187f0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 ents..** The fir
18800 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 st argument is a
18810 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 n integer which
18820 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 is 0 to disable
18830 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a FK enforcement,.
18840 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 ** positive to e
18850 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 nable FK enforce
18860 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 ment or negative
18870 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 to leave FK enf
18880 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 orcement.** unch
18890 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f anged. The seco
188a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
188b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
188c0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 integer into whi
188d0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e ch.** is written
188e0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 0 or 1 to indic
188f0 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 ate whether FK e
18900 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 nforcement is of
18910 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f f or on.** follo
18920 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 wing this call.
18930 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
18940 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e meter may be a N
18950 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a ULL pointer, in.
18960 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 ** which case th
18970 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 e FK enforcement
18980 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 setting is not
18990 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c reported back. <
189a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
189b0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
189c0 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 NABLE_TRIGGER</d
189d0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
189e0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 option is used
189f0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 to enable or dis
18a00 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 able [CREATE TRI
18a10 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d GGER | triggers]
18a20 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c ..** There shoul
18a30 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f d be two additio
18a40 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a nal arguments..*
18a50 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
18a60 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 ment is an integ
18a70 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f er which is 0 to
18a80 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 disable trigger
18a90 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 s,.** positive t
18aa0 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 o enable trigger
18ab0 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f s or negative to
18ac0 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 leave the setti
18ad0 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a ng unchanged..**
18ae0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
18af0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 meter is a point
18b00 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 er to an integer
18b10 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 into which.** i
18b20 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 s written 0 or 1
18b30 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 to indicate whe
18b40 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 ther triggers ar
18b50 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e e disabled or en
18b60 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 abled.** followi
18b70 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 ng this call. T
18b80 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
18b90 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c ter may be a NUL
18ba0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a L pointer, in.**
18bb0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 which case the
18bc0 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 trigger setting
18bd0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 is not reported
18be0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a back. </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 54 53 ONFIG_ENABLE_FTS
18c10 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 3_TOKENIZER</dt>
18c20 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
18c30 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f ption is used to
18c40 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 enable or disab
18c50 6c 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d le the two-argum
18c60 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f ent.** version o
18c70 66 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 f the [fts3_toke
18c80 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f nizer()] functio
18c90 6e 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20 n which is part
18ca0 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d of the.** [FTS3]
18cb0 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 full-text searc
18cc0 68 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 h engine extensi
18cd0 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f on..** There sho
18ce0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 uld be two addit
18cf0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e ional arguments.
18d00 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
18d10 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 gument is an int
18d20 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 eger which is 0
18d30 74 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f to disable fts3_
18d40 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a tokenizer() or.*
18d50 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e * positive to en
18d60 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 able fts3_tokeni
18d70 7a 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 zer() or negativ
18d80 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 e to leave the s
18d90 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e etting.** unchan
18da0 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f ged..** The seco
18db0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
18dc0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
18dd0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 integer into whi
18de0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e ch.** is written
18df0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 0 or 1 to indic
18e00 61 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33 ate whether fts3
18e10 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 _tokenizer is di
18e20 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 sabled or enable
18e30 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 d.** following t
18e40 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 his call. The s
18e50 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
18e60 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f may be a NULL po
18e70 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 inter, in.** whi
18e80 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 ch case the new
18e90 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 setting is not r
18ea0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f eported back. </
18eb0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
18ec0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e LITE_DBCONFIG_EN
18ed0 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 ABLE_LOAD_EXTENS
18ee0 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ION</dt>.** <dd>
18ef0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 ^This option is
18f00 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 used to enable
18f10 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b or disable the [
18f20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 sqlite3_load_ext
18f30 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 ension()].** int
18f40 65 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65 erface independe
18f50 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 ntly of the [loa
18f60 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 d_extension()] S
18f70 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 QL function..**
18f80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 The [sqlite3_ena
18f90 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 ble_load_extensi
18fa0 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 on()] API enable
18fb0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f s or disables bo
18fc0 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 th the.** C-API
18fd0 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 [sqlite3_load_ex
18fe0 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 tension()] and t
18ff0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
19000 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 [load_extension(
19010 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f )]..** There sho
19020 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 uld be two addit
19030 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e ional arguments.
19040 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72 .** When the fir
19050 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
19060 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
19070 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 1, then only th
19080 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e e C-API is.** en
19090 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51 abled and the SQ
190a0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 L function remai
190b0 6e 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66 ns disabled. If
190c0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
190d0 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 ent to.** this i
190e0 6e 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74 nterface is 0, t
190f0 68 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41 hen both the C-A
19100 50 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 PI and the SQL f
19110 75 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61 unction are disa
19120 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 bled..** If the
19130 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 first argument i
19140 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 s -1, then no ch
19150 61 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74 anges are made t
19160 6f 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65 o state of eithe
19170 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f r the.** C-API o
19180 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 r the SQL functi
19190 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e on..** The secon
191a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 d parameter is a
191b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
191c0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 nteger into whic
191d0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 h.** is written
191e0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 0 or 1 to indica
191f0 74 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69 te whether [sqli
19200 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 te3_load_extensi
19210 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a on()] interface.
19220 2a 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f ** is disabled o
19230 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 r enabled follow
19240 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 ing this call.
19250 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
19260 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 eter may.** be a
19270 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 NULL pointer, i
19280 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 n which case the
19290 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 new setting is
192a0 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 not reported bac
192b0 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a k..** </dd>.**.*
192c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 * <dt>SQLITE_DBC
192d0 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 ONFIG_MAINDBNAME
192e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
192f0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 his option is us
19300 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 ed to change the
19310 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 name of the "ma
19320 69 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 in" database.**
19330 73 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f schema. ^The so
19340 6c 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 le argument is a
19350 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f pointer to a co
19360 6e 73 74 61 6e 74 20 55 54 46 38 20 73 74 72 69 nstant UTF8 stri
19370 6e 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c ng.** which will
19380 20 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 become the new
19390 73 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 schema name in p
193a0 6c 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 lace of "main".
193b0 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 ^SQLite.** does
193c0 20 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 not make a copy
193d0 20 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e of the new main
193e0 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 schema name str
193f0 69 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c ing, so the appl
19400 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 ication.** must
19410 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 ensure that the
19420 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 argument passed
19430 69 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 into this DBCONF
19440 49 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 IG option is unc
19450 68 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 hanged.** until
19460 61 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61 after the databa
19470 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c se connection cl
19480 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a oses..** </dd>.*
19490 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
194a0 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 DBCONFIG_NO_CKPT
194b0 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a _ON_CLOSE</dt>.*
194c0 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 * <dd> Usually,
194d0 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 when a database
194e0 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 in wal mode is c
194f0 6c 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 losed or detache
19500 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 d from a .** dat
19510 61 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 abase handle, SQ
19520 4c 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 Lite checks if t
19530 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 his will mean th
19540 61 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 at there are now
19550 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 no .** connecti
19560 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 ons at all to th
19570 65 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 e database. If s
19580 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 o, it performs a
19590 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 checkpoint .**
195a0 6f 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 operation before
195b0 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e closing the con
195c0 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 nection. This op
195d0 74 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 tion may be used
195e0 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 to.** override
195f0 74 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 this behaviour.
19600 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
19610 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 ter passed to th
19620 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 is operation.**
19630 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 is an integer -
19640 70 6f 73 69 74 69 76 65 20 74 6f 20 64 69 73 61 positive to disa
19650 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d ble checkpoints-
19660 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 on-close, or zer
19670 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c o (the.** defaul
19680 74 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 t) to enable the
19690 6d 2c 20 61 6e 64 20 6e 65 67 61 74 69 76 65 20 m, and negative
196a0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 to leave the set
196b0 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a ting unchanged..
196c0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 ** The second pa
196d0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 rameter is a poi
196e0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
196f0 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 er.** into which
19700 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 is written 0 or
19710 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 1 to indicate w
19720 68 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e hether checkpoin
19730 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 ts-on-close.** h
19740 61 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 ave been disable
19750 64 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 d - 0 if they ar
19760 65 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 e not disabled,
19770 31 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 1 if they are..*
19780 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 * </dd>.**.** <d
19790 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
197a0 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 G_ENABLE_QPSG</d
197b0 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 t>.** <dd>^(The
197c0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
197d0 45 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 ENABLE_QPSG opti
197e0 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 on activates or
197f0 64 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 deactivates.** t
19800 68 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 he [query planne
19810 72 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72 r stability guar
19820 61 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20 antee] (QPSG).
19830 57 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73 When the QPSG is
19840 20 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 active,.** a si
19850 6e 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73 ngle SQL query s
19860 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c tatement will al
19870 77 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d ways use the sam
19880 65 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 e algorithm rega
19890 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c rdless.** of val
198a0 75 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 ues of [bound pa
198b0 72 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 rameters].)^ The
198c0 20 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73 QPSG disables s
198d0 6f 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 ome query optimi
198e0 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 zations.** that
198f0 6c 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75 look at the valu
19900 65 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 es of bound para
19910 6d 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61 meters, which ca
19920 6e 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 n make some quer
19930 69 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 ies.** slower.
19940 42 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73 But the QPSG has
19950 20 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f the advantage o
19960 66 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62 f more predictab
19970 6c 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69 le behavior. Wi
19980 74 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61 th.** the QPSG a
19990 63 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69 ctive, SQLite wi
199a0 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 ll always use th
199b0 65 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61 e same query pla
199c0 6e 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61 n in the field a
199d0 73 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75 s.** was used du
199e0 72 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20 ring testing in
199f0 74 68 65 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 the lab..** The
19a00 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
19a10 6f 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 o this setting i
19a20 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 s an integer whi
19a30 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 ch is 0 to disab
19a40 6c 65 20 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c le .** the QPSG,
19a50 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 positive to ena
19a60 62 6c 65 20 51 50 53 47 2c 20 6f 72 20 6e 65 67 ble QPSG, or neg
19a70 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 ative to leave t
19a80 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e he setting.** un
19a90 63 68 61 6e 67 65 64 2e 20 54 68 65 20 73 65 63 changed. The sec
19aa0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
19ab0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
19ac0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 integer into wh
19ad0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 ich.** is writte
19ae0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 n 0 or 1 to indi
19af0 63 61 74 65 20 77 68 65 74 68 65 72 20 74 68 65 cate whether the
19b00 20 51 50 53 47 20 69 73 20 64 69 73 61 62 6c 65 QPSG is disable
19b10 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 d or enabled.**
19b20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 following this c
19b30 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a all..** </dd>.**
19b40 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
19b50 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f BCONFIG_TRIGGER_
19b60 45 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e EQP</dt>.** <dd>
19b70 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 By default, the
19b80 20 6f 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41 output of EXPLA
19b90 49 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f IN QUERY PLAN co
19ba0 6d 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 mmands does not
19bb0 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 .** include outp
19bc0 75 74 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 ut for any opera
19bd0 74 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 tions performed
19be0 62 79 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 by trigger progr
19bf0 61 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 ams. This.** opt
19c00 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73 ion is used to s
19c10 65 74 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65 et or clear (the
19c20 20 64 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67 default) a flag
19c30 20 74 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68 that governs th
19c40 69 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 is.** behavior.
19c50 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
19c60 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 ter passed to th
19c70 69 73 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 is operation is
19c80 61 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 an integer -.**
19c90 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 positive to enab
19ca0 6c 65 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72 le output for tr
19cb0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 igger programs,
19cc0 6f 72 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 or zero to disab
19cd0 6c 65 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 le it,.** or neg
19ce0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 ative to leave t
19cf0 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 he setting uncha
19d00 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 nged..** The sec
19d10 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
19d20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
19d30 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 integer into wh
19d40 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a ich is written .
19d50 2a 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 ** 0 or 1 to ind
19d60 69 63 61 74 65 20 77 68 65 74 68 65 72 20 6f 75 icate whether ou
19d70 74 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 tput-for-trigger
19d80 73 20 68 61 73 20 62 65 65 6e 20 64 69 73 61 62 s has been disab
19d90 6c 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 led - 0 if .** i
19da0 74 20 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 t is not disable
19db0 64 2c 20 31 20 69 66 20 69 74 20 69 73 2e 20 20 d, 1 if it is.
19dc0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 .** </dd>.** </d
19dd0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
19de0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 LITE_DBCONFIG_MA
19df0 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 INDBNAME
19e00 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 1000 /* cons
19e10 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 t char* */.#defi
19e20 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
19e30 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 IG_LOOKASIDE
19e40 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 1001 /*
19e50 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a void* int int *
19e60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
19e70 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
19e80 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 _FKEY
19e90 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 1002 /* int int*
19ea0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
19eb0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
19ec0 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 LE_TRIGGER
19ed0 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 1003 /* int in
19ee0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t* */.#define SQ
19ef0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e LITE_DBCONFIG_EN
19f00 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 ABLE_FTS3_TOKENI
19f10 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 ZER 1004 /* int
19f20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int* */.#define
19f30 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
19f40 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 ENABLE_LOAD_EXTE
19f50 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e NSION 1005 /* in
19f60 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e t int* */.#defin
19f70 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
19f80 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f G_NO_CKPT_ON_CLO
19f90 53 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 SE 1006 /*
19fa0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 int int* */.#def
19fb0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e ine SQLITE_DBCON
19fc0 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 FIG_ENABLE_QPSG
19fd0 20 20 20 20 20 20 20 20 20 20 31 30 30 37 20 2f 1007 /
19fe0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 * int int* */.#d
19ff0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 efine SQLITE_DBC
1a000 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 ONFIG_TRIGGER_EQ
1a010 50 20 20 20 20 20 20 20 20 20 20 20 31 30 30 38 P 1008
1a020 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a /* int int* */.
1a030 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1a040 42 43 4f 4e 46 49 47 5f 4d 41 58 20 20 20 20 20 BCONFIG_MAX
1a050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30 10
1a060 30 38 20 2f 2a 20 4c 61 72 67 65 73 74 20 44 42 08 /* Largest DB
1a070 43 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a CONFIG */../*.**
1a080 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c CAPI3REF: Enabl
1a090 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 e Or Disable Ext
1a0a0 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 ended Result Cod
1a0b0 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 es.** METHOD: sq
1a0c0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 lite3.**.** ^The
1a0d0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 sqlite3_extende
1a0e0 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 d_result_codes()
1a0f0 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 routine enables
1a100 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 or disables the
1a110 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 .** [extended re
1a120 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 sult codes] feat
1a130 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e ure of SQLite. ^
1a140 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 The extended res
1a150 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 ult.** codes are
1a160 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
1a170 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 ault for histori
1a180 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 cal compatibilit
1a190 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 y..*/.int sqlite
1a1a0 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 3_extended_resul
1a1b0 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a t_codes(sqlite3*
1a1c0 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f , int onoff);../
1a1d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c *.** CAPI3REF: L
1a1e0 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 ast Insert Rowid
1a1f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
1a200 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 te3.**.** ^Each
1a210 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 entry in most SQ
1a220 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 Lite tables (exc
1a230 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 ept for [WITHOUT
1a240 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a ROWID] tables).
1a250 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 ** has a unique
1a260 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 64-bit signed.**
1a270 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c integer key cal
1a280 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c led the [ROWID |
1a290 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 "rowid"]. ^The
1a2a0 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 rowid is always
1a2b0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 available.** as
1a2c0 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f an undeclared co
1a2d0 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 lumn named ROWID
1a2e0 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 , OID, or _ROWID
1a2f0 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f _ as long as tho
1a300 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 se.** names are
1a310 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 not also used by
1a320 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c explicitly decl
1a330 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 ared columns. ^I
1a340 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 f.** the table h
1a350 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 as a column of t
1a360 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 ype [INTEGER PRI
1a370 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 MARY KEY] then t
1a380 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 hat column.** is
1a390 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 another alias f
1a3a0 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a or the rowid..**
1a3b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1a3c0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
1a3d0 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 id(D) interface
1a3e0 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 usually returns
1a3f0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a the [rowid] of.*
1a400 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e * the most recen
1a410 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e t successful [IN
1a420 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 SERT] into a row
1a430 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 id table or [vir
1a440 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f tual table].** o
1a450 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 n database conne
1a460 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74 ction D. ^Insert
1a470 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 s into [WITHOUT
1a480 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 ROWID] tables ar
1a490 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65 e not.** recorde
1a4a0 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 d. ^If no succes
1a4b0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 sful [INSERT]s i
1a4c0 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 nto rowid tables
1a4d0 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 have ever occur
1a4e0 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 red .** on the d
1a4f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1a500 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69 74 on D, then sqlit
1a510 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
1a520 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 owid(D) returns
1a530 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 .** zero..**.**
1a540 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e 67 As well as being
1a550 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61 6c set automatical
1a560 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65 20 69 ly as rows are i
1a570 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61 74 nserted into dat
1a580 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c abase.** tables,
1a590 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
1a5a0 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 ned by this func
1a5b0 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20 tion may be set
1a5c0 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a explicitly by.**
1a5d0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 [sqlite3_set_la
1a5e0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
1a5f0 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 )].**.** Some vi
1a600 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c rtual table impl
1a610 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 ementations may
1a620 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74 6f INSERT rows into
1a630 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61 73 rowid tables as
1a640 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d .** part of comm
1a650 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61 63 itting a transac
1a660 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c tion (e.g. to fl
1a670 75 73 68 20 64 61 74 61 20 61 63 63 75 6d 75 6c ush data accumul
1a680 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a ated in memory.*
1a690 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74 * to disk). In t
1a6a0 68 69 73 20 63 61 73 65 20 73 75 62 73 65 71 75 his case subsequ
1a6b0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68 69 ent calls to thi
1a6c0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
1a6d0 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61 n the rowid.** a
1a6e0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
1a6f0 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e hese internal IN
1a700 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c SERT operations,
1a710 20 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f 20 which leads to
1a720 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65 20 .** unintuitive
1a730 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61 6c results. Virtual
1a740 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 table implement
1a750 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20 77 ations that do w
1a760 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a rite to rowid.**
1a770 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73 20 tables in this
1a780 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74 68 way can avoid th
1a790 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72 65 is problem by re
1a7a0 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69 67 storing the orig
1a7b0 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76 inal .** rowid v
1a7c0 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 alue using [sqli
1a7d0 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 te3_set_last_ins
1a7e0 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65 66 ert_rowid()] bef
1a7f0 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a ore returning .*
1a800 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65 * control to the
1a810 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 user..**.** ^(I
1a820 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 f an [INSERT] oc
1a830 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 curs within a tr
1a840 69 67 67 65 72 20 74 68 65 6e 20 74 68 69 73 20 igger then this
1a850 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a routine will .**
1a860 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 return the [row
1a870 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 id] of the inser
1a880 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 ted row as long
1a890 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 as the trigger i
1a8a0 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f s .** running. O
1a8b0 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 nce the trigger
1a8c0 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74 68 program ends, th
1a8d0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
1a8e0 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 .** by this rou
1a8f0 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 tine reverts to
1a900 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f what it was befo
1a910 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 77 re the trigger w
1a920 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a as fired.)^.**.*
1a930 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 * ^An [INSERT] t
1a940 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f hat fails due to
1a950 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 a constraint vi
1a960 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 olation is not a
1a970 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b .** successful [
1a980 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 INSERT] and does
1a990 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 not change the
1a9a0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
1a9b0 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e y this.** routin
1a9c0 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 e. ^Thus INSERT
1a9d0 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 OR FAIL, INSERT
1a9e0 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 OR IGNORE, INSE
1a9f0 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a RT OR ROLLBACK,.
1aa00 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 ** and INSERT OR
1aa10 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 ABORT make no c
1aa20 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 hanges to the re
1aa30 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
1aa40 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 is.** routine wh
1aa50 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 en their inserti
1aa60 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 on fails. ^(Whe
1aa70 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c n INSERT OR REPL
1aa80 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 ACE.** encounter
1aa90 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 s a constraint v
1aaa0 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 iolation, it doe
1aab0 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 s not fail. The
1aac0 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 .** INSERT conti
1aad0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 nues to completi
1aae0 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e on after deletin
1aaf0 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 g rows that caus
1ab00 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 ed.** the constr
1ab10 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 aint problem so
1ab20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 INSERT OR REPLAC
1ab30 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 E will always ch
1ab40 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 ange.** the retu
1ab50 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 rn value of this
1ab60 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a interface.)^.**
1ab70 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 .** ^For the pur
1ab80 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f poses of this ro
1ab90 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 utine, an [INSER
1aba0 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 T] is considered
1abb0 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 to.** be succes
1abc0 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 sful even if it
1abd0 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 is subsequently
1abe0 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a rolled back..**.
1abf0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
1ac00 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 is accessible t
1ac10 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 o SQL statements
1ac20 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 via the.** [las
1ac30 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 t_insert_rowid()
1ac40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a SQL function]..
1ac50 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 **.** If a separ
1ac60 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f ate thread perfo
1ac70 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 rms a new [INSER
1ac80 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a T] on the same.*
1ac90 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
1aca0 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 ction while the
1acb0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e [sqlite3_last_in
1acc0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a sert_rowid()].**
1acd0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
1ace0 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 ning and thus ch
1acf0 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 anges the last i
1ad00 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a nsert [rowid],.*
1ad10 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 * then the value
1ad20 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 returned by [sq
1ad30 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
1ad40 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a t_rowid()] is.**
1ad50 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 unpredictable a
1ad60 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 nd might not equ
1ad70 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c al either the ol
1ad80 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 d or the new.**
1ad90 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 last insert [row
1ada0 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f id]..*/.sqlite3_
1adb0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 int64 sqlite3_la
1adc0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
1add0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
1ade0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 * CAPI3REF: Set
1adf0 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20 the Last Insert
1ae00 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 Rowid value..**
1ae10 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
1ae20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
1ae30 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 3_set_last_inser
1ae40 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 t_rowid(D, R) me
1ae50 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 thod allows the
1ae60 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a application to.*
1ae70 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 * set the value
1ae80 72 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c returned by call
1ae90 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 ing sqlite3_last
1aea0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 _insert_rowid(D)
1aeb0 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 to R .** withou
1aec0 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f t inserting a ro
1aed0 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 w into the datab
1aee0 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c ase..*/.void sql
1aef0 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e ite3_set_last_in
1af00 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 sert_rowid(sqlit
1af10 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 e3*,sqlite3_int6
1af20 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 4);../*.** CAPI3
1af30 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e REF: Count The N
1af40 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f umber Of Rows Mo
1af50 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 dified.** METHOD
1af60 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
1af70 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 ^This function r
1af80 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
1af90 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 r of rows modifi
1afa0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a ed, inserted or.
1afb0 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 ** deleted by th
1afc0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 e most recently
1afd0 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 completed INSERT
1afe0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 , UPDATE or DELE
1aff0 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 TE.** statement
1b000 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 on the database
1b010 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 connection speci
1b020 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 fied by the only
1b030 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e parameter..** ^
1b040 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 Executing any ot
1b050 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 her type of SQL
1b060 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e statement does n
1b070 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 ot modify the va
1b080 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lue.** returned
1b090 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e by this function
1b0a0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 ..**.** ^Only ch
1b0b0 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 anges made direc
1b0c0 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 tly by the INSER
1b0d0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c T, UPDATE or DEL
1b0e0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 ETE statement ar
1b0f0 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 e.** considered
1b100 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e - auxiliary chan
1b110 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 ges caused by [C
1b120 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 REATE TRIGGER |
1b130 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b triggers], .** [
1b140 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 foreign key acti
1b150 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 ons] or [REPLACE
1b160 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 ] constraint res
1b170 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 olution are not
1b180 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 counted..** .**
1b190 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 Changes to a vie
1b1a0 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 w that are inter
1b1b0 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 cepted by .** [I
1b1c0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 NSTEAD OF trigge
1b1d0 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 r | INSTEAD OF t
1b1e0 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 riggers] are not
1b1f0 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 counted. ^The v
1b200 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 alue .** returne
1b210 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 d by sqlite3_cha
1b220 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 nges() immediate
1b230 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 ly after an INSE
1b240 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a RT, UPDATE or .*
1b250 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 * DELETE stateme
1b260 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 nt run on a view
1b270 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e is always zero.
1b280 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 Only changes ma
1b290 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 de to real .** t
1b2a0 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 ables are counte
1b2b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 d..**.** Things
1b2c0 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 are more complic
1b2d0 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 ated if the sqli
1b2e0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 te3_changes() fu
1b2f0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 nction is.** exe
1b300 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 cuted while a tr
1b310 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 igger program is
1b320 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d running. This m
1b330 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 ay happen if the
1b340 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 .** program uses
1b350 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 the [changes()
1b360 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f SQL function], o
1b370 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 r if some other
1b380 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 callback.** func
1b390 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c tion invokes sql
1b3a0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 ite3_changes() d
1b3b0 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 irectly. Essenti
1b3c0 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c ally:.** .** <ul
1b3d0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 >.** <li> ^(Be
1b3e0 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 fore entering a
1b3f0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 trigger program
1b400 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
1b410 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 ed by.**
1b420 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
1b430 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 ) function is sa
1b440 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 ved. After the t
1b450 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a rigger program .
1b460 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 ** has fi
1b470 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 nished, the orig
1b480 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 inal value is re
1b490 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a stored.)^.** .**
1b4a0 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e <li> ^(Within
1b4b0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 a trigger progr
1b4c0 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 am each INSERT,
1b4d0 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 UPDATE and DELET
1b4e0 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 E .** sta
1b4f0 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 tement sets the
1b500 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
1b510 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 y sqlite3_change
1b520 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 s() .** u
1b530 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 pon completion a
1b540 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 s normal. Of cou
1b550 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 rse, this value
1b560 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 will not include
1b570 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 .** any
1b580 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 changes performe
1b590 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 d by sub-trigger
1b5a0 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 s, as the sqlite
1b5b0 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 3_changes() .**
1b5c0 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c value wil
1b5d0 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 l be saved and r
1b5e0 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 estored after ea
1b5f0 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 ch sub-trigger h
1b600 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 as run.)^.** </u
1b610 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 l>.** .** ^This
1b620 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 means that if th
1b630 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 e changes() SQL
1b640 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d function (or sim
1b650 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a ilar) is used.**
1b660 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e by the first IN
1b670 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 SERT, UPDATE or
1b680 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
1b690 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 within a trigge
1b6a0 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e r, it .** return
1b6b0 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 s the value as s
1b6c0 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c et when the call
1b6d0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 ing statement be
1b6e0 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a gan executing..*
1b6f0 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 * ^If it is used
1b700 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f by the second o
1b710 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 r subsequent suc
1b720 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 h statement with
1b730 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a in a trigger .**
1b740 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 program, the va
1b750 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 lue returned ref
1b760 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 lects the number
1b770 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 of rows modifie
1b780 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 d by the .** pre
1b790 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 vious INSERT, UP
1b7a0 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 DATE or DELETE s
1b7b0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 tatement within
1b7c0 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 the same trigger
1b7d0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
1b7e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f the [sqlite3_to
1b7f0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 tal_changes()] i
1b800 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a nterface, the.**
1b810 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 [count_changes
1b820 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 pragma], and the
1b830 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 [changes() SQL
1b840 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
1b850 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
1b860 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e hread makes chan
1b870 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 ges on the same
1b880 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1b890 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 ion.** while [sq
1b8a0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d lite3_changes()]
1b8b0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e is running then
1b8c0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
1b8d0 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 ned.** is unpred
1b8e0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 ictable and not
1b8f0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 meaningful..*/.i
1b900 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 nt sqlite3_chang
1b910 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
1b920 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
1b930 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 otal Number Of R
1b940 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 ows Modified.**
1b950 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
1b960 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 **.** ^This func
1b970 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
1b980 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 total number of
1b990 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 rows inserted,
1b9a0 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 modified or.** d
1b9b0 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 eleted by all [I
1b9c0 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d NSERT], [UPDATE]
1b9d0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 or [DELETE] sta
1b9e0 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 tements complete
1b9f0 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 d.** since the d
1ba00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1ba10 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 on was opened, i
1ba20 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 ncluding those e
1ba30 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 xecuted as.** pa
1ba40 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 rt of trigger pr
1ba50 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 ograms. ^Executi
1ba60 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 ng any other typ
1ba70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 e of SQL stateme
1ba80 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 nt.** does not a
1ba90 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 ffect the value
1baa0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
1bab0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
1bac0 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 s()..** .** ^Cha
1bad0 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 nges made as par
1bae0 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 t of [foreign ke
1baf0 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 y actions] are i
1bb00 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a ncluded in the.*
1bb10 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f * count, but tho
1bb20 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 se made as part
1bb30 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 of REPLACE const
1bb40 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e raint resolution
1bb50 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 are.** not. ^Ch
1bb60 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 anges to a view
1bb70 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 that are interce
1bb80 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 pted by INSTEAD
1bb90 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 OF triggers .**
1bba0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e are not counted.
1bbb0 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f .** .** See also
1bbc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 the [sqlite3_ch
1bbd0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 anges()] interfa
1bbe0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e ce, the.** [coun
1bbf0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 t_changes pragma
1bc00 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 ], and the [tota
1bc10 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 l_changes() SQL
1bc20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
1bc30 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
1bc40 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e hread makes chan
1bc50 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 ges on the same
1bc60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1bc70 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 ion.** while [sq
1bc80 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
1bc90 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e ges()] is runnin
1bca0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 g then the value
1bcb0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 .** returned is
1bcc0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
1bcd0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c d not meaningful
1bce0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
1bcf0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 _total_changes(s
1bd00 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
1bd10 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 CAPI3REF: Inter
1bd20 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e rupt A Long-Runn
1bd30 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 ing Query.** MET
1bd40 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
1bd50 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
1bd60 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e n causes any pen
1bd70 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 ding database op
1bd80 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 eration to abort
1bd90 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 and.** return a
1bda0 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f t its earliest o
1bdb0 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 pportunity. This
1bdc0 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 routine is typi
1bdd0 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 cally.** called
1bde0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 in response to a
1bdf0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 user action suc
1be00 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 h as pressing "C
1be10 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 ancel".** or Ctr
1be20 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 l-C where the us
1be30 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 er wants a long
1be40 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 query operation
1be50 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 to halt.** immed
1be60 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 iately..**.** ^I
1be70 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c t is safe to cal
1be80 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 l this routine f
1be90 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 rom a thread dif
1bea0 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a ferent from the.
1beb0 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 ** thread that i
1bec0 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e s currently runn
1bed0 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 ing the database
1bee0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 operation. But
1bef0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 it.** is not sa
1bf00 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 fe to call this
1bf10 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b routine with a [
1bf20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1bf30 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 ion] that.** is
1bf40 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 closed or might
1bf50 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c close before sql
1bf60 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
1bf70 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
1bf80 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 ^If an SQL opera
1bf90 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 tion is very nea
1bfa0 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 rly finished at
1bfb0 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a the time when.**
1bfc0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
1bfd0 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 pt() is called,
1bfe0 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f then it might no
1bff0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 t have an opport
1c000 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 unity.** to be i
1c010 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d nterrupted and m
1c020 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f ight continue to
1c030 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a completion..**.
1c040 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 ** ^An SQL opera
1c050 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 tion that is int
1c060 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 errupted will re
1c070 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 turn [SQLITE_INT
1c080 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 ERRUPT]..** ^If
1c090 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 the interrupted
1c0a0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 SQL operation is
1c0b0 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 an INSERT, UPDA
1c0c0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a TE, or DELETE.**
1c0d0 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 that is inside
1c0e0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e an explicit tran
1c0f0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 saction, then th
1c100 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 e entire transac
1c110 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 tion.** will be
1c120 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f rolled back auto
1c130 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a matically..**.**
1c140 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
1c150 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 terrupt(D) call
1c160 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 is in effect unt
1c170 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 il all currently
1c180 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 running.** SQL
1c190 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 statements on [d
1c1a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1c1b0 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 on] D complete.
1c1c0 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 ^Any new SQL st
1c1d0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 atements.** that
1c1e0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 are started aft
1c1f0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 er the sqlite3_i
1c200 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 nterrupt() call
1c210 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a and before the .
1c220 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 ** running state
1c230 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 ments reaches ze
1c240 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 ro are interrupt
1c250 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 ed as if they ha
1c260 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e d been.** runnin
1c270 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 g prior to the s
1c280 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1c290 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 () call. ^New S
1c2a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
1c2b0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 that are starte
1c2c0 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e d after the runn
1c2d0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f ing statement co
1c2e0 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f unt reaches zero
1c2f0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 are.** not effe
1c300 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 cted by the sqli
1c310 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e te3_interrupt().
1c320 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 .** ^A call to s
1c330 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1c340 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 (D) that occurs
1c350 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e when there are n
1c360 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c o running.** SQL
1c370 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 statements is a
1c380 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e no-op and has n
1c390 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 o effect on SQL
1c3a0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 statements.** th
1c3b0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 at are started a
1c3c0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 fter the sqlite3
1c3d0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c _interrupt() cal
1c3e0 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f l returns..*/.vo
1c3f0 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 id sqlite3_inter
1c400 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a rupt(sqlite3*);.
1c410 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1c420 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e Determine If An
1c430 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 SQL Statement I
1c440 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a s Complete.**.**
1c450 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1c460 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e are useful durin
1c470 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 g command-line i
1c480 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e nput to determin
1c490 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 e if the.** curr
1c4a0 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 ently entered te
1c4b0 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d xt seems to form
1c4c0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 a complete SQL
1c4d0 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 statement or.**
1c4e0 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e if additional in
1c4f0 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 put is needed be
1c500 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 fore sending the
1c510 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 text into.** SQ
1c520 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 Lite for parsing
1c530 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e . ^These routin
1c540 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 es return 1 if t
1c550 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a he input string.
1c560 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 ** appears to be
1c570 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 a complete SQL
1c580 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 statement. ^A s
1c590 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 tatement is judg
1c5a0 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 ed to be.** comp
1c5b0 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 lete if it ends
1c5c0 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e with a semicolon
1c5d0 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f token and is no
1c5e0 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a t a prefix of a.
1c5f0 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 ** well-formed C
1c600 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 REATE TRIGGER st
1c610 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 atement. ^Semic
1c620 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 olons that are e
1c630 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a mbedded within.*
1c640 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c * string literal
1c650 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e s or quoted iden
1c660 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 tifier names or
1c670 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 comments are not
1c680 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 .** independent
1c690 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 tokens (they are
1c6a0 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b part of the tok
1c6b0 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 en in which they
1c6c0 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 are.** embedded
1c6d0 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f ) and thus do no
1c6e0 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 t count as a sta
1c6f0 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f tement terminato
1c700 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a r. ^Whitespace.
1c710 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 ** and comments
1c720 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 that follow the
1c730 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 final semicolon
1c740 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a are ignored..**.
1c750 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
1c760 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 es return 0 if t
1c770 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
1c780 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 incomplete. ^If
1c790 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c a.** memory all
1c7a0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 ocation fails, t
1c7b0 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d hen SQLITE_NOMEM
1c7c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
1c7d0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
1c7e0 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 nes do not parse
1c7f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
1c800 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c nts thus.** will
1c810 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 not detect synt
1c820 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 actically incorr
1c830 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e ect SQL..**.** ^
1c840 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e (If SQLite has n
1c850 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 ot been initiali
1c860 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 zed using [sqlit
1c870 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
1c880 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e prior .** to in
1c890 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 voking sqlite3_c
1c8a0 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e omplete16() then
1c8b0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
1c8c0 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
1c8d0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
1c8e0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d y by sqlite3_com
1c8f0 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 plete16(). If t
1c900 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 hat initializati
1c910 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 on fails,.** the
1c920 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c n the return val
1c930 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
1c940 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c complete16() wil
1c950 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a l be non-zero.**
1c960 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 regardless of w
1c970 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
1c980 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 e input SQL is c
1c990 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a omplete.)^.**.**
1c9a0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 The input to [s
1c9b0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 qlite3_complete(
1c9c0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 )] must be a zer
1c9d0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
1c9e0 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a UTF-8 string..**
1c9f0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f .** The input to
1ca00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 [sqlite3_comple
1ca10 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 te16()] must be
1ca20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
1ca30 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 d.** UTF-16 stri
1ca40 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 ng in native byt
1ca50 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 e order..*/.int
1ca60 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
1ca70 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c (const char *sql
1ca80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
1ca90 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 omplete16(const
1caa0 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a void *sql);../*.
1cab0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 ** CAPI3REF: Reg
1cac0 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b ister A Callback
1cad0 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 To Handle SQLIT
1cae0 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a E_BUSY Errors.**
1caf0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 KEYWORDS: {busy
1cb00 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 -handler callbac
1cb10 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 k} {busy handler
1cb20 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c }.** METHOD: sql
1cb30 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ite3.**.** ^The
1cb40 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
1cb50 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 dler(D,X,P) rout
1cb60 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 ine sets a callb
1cb70 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a ack function X.*
1cb80 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 * that might be
1cb90 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 invoked with arg
1cba0 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 ument P whenever
1cbb0 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 .** an attempt i
1cbc0 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 s made to access
1cbd0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c a database tabl
1cbe0 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 e associated wit
1cbf0 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 h.** [database c
1cc00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 onnection] D whe
1cc10 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 n another thread
1cc20 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 .** or process h
1cc30 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 as the table loc
1cc40 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ked..** The sqli
1cc50 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
1cc60 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
1cc70 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e used to implemen
1cc80 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 t.** [sqlite3_bu
1cc90 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e sy_timeout()] an
1cca0 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 d [PRAGMA busy_t
1ccb0 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e imeout]..**.** ^
1ccc0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c If the busy call
1ccd0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 back is NULL, th
1cce0 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d en [SQLITE_BUSY]
1ccf0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
1cd00 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e immediately upon
1cd10 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 encountering th
1cd20 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 e lock. ^If the
1cd30 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a busy callback.*
1cd40 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 * is not NULL, t
1cd50 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
1cd60 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 might be invoke
1cd70 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d d with two argum
1cd80 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ents..**.** ^The
1cd90 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
1cda0 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 to the busy hand
1cdb0 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ler is a copy of
1cdc0 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 the void* point
1cdd0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 er which.** is t
1cde0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
1cdf0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 t to sqlite3_bus
1ce00 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 y_handler(). ^T
1ce10 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
1ce20 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 nt to.** the bus
1ce30 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 y handler callba
1ce40 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 ck is the number
1ce50 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 of times that t
1ce60 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
1ce70 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f has.** been invo
1ce80 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 ked previously f
1ce90 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b or the same lock
1cea0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 ing event. ^If
1ceb0 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c the.** busy call
1cec0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 back returns 0,
1ced0 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e then no addition
1cee0 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 al attempts are
1cef0 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 made to.** acces
1cf00 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 s the database a
1cf10 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d nd [SQLITE_BUSY]
1cf20 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 is returned.**
1cf30 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 to the applicati
1cf40 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 on..** ^If the c
1cf50 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
1cf60 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 non-zero, then a
1cf70 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a nother attempt.*
1cf80 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 * is made to acc
1cf90 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ess the database
1cfa0 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 and the cycle r
1cfb0 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 epeats..**.** Th
1cfc0 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 e presence of a
1cfd0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 busy handler doe
1cfe0 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 s not guarantee
1cff0 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 that it will be
1d000 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 invoked.** when
1d010 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f there is lock co
1d020 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 ntention. ^If SQ
1d030 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 Lite determines
1d040 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 that invoking th
1d050 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 e busy.** handle
1d060 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 r could result i
1d070 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 n a deadlock, it
1d080 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 will go ahead a
1d090 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 nd return [SQLIT
1d0a0 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 E_BUSY].** to th
1d0b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e e application in
1d0c0 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e stead of invokin
1d0d0 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 g the .** busy h
1d0e0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 andler..** Consi
1d0f0 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 der a scenario w
1d100 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 here one process
1d110 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 is holding a re
1d120 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 ad lock that.**
1d130 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 it is trying to
1d140 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 promote to a res
1d150 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a erved lock and.*
1d160 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 * a second proce
1d170 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 ss is holding a
1d180 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 reserved lock th
1d190 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a at it is trying.
1d1a0 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f ** to promote to
1d1b0 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f an exclusive lo
1d1c0 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 ck. The first p
1d1d0 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 rocess cannot pr
1d1e0 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 oceed.** because
1d1f0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 it is blocked b
1d200 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 y the second and
1d210 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 the second proc
1d220 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 ess cannot.** pr
1d230 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 oceed because it
1d240 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 is blocked by t
1d250 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f he first. If bo
1d260 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 th processes.**
1d270 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 invoke the busy
1d280 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 handlers, neithe
1d290 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 r will make any
1d2a0 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 progress. There
1d2b0 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 fore,.** SQLite
1d2c0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
1d2d0 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 BUSY] for the fi
1d2e0 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 rst process, hop
1d2f0 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a ing that this.**
1d300 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 will induce the
1d310 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 first process t
1d320 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 o release its re
1d330 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f ad lock and allo
1d340 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 w.** the second
1d350 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 process to proce
1d360 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 ed..**.** ^The d
1d370 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c efault busy call
1d380 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a back is NULL..**
1d390 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 .** ^(There can
1d3a0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 only be a single
1d3b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 busy handler de
1d3c0 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a fined for each.*
1d3d0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
1d3e0 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e ection]. Settin
1d3f0 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e g a new busy han
1d400 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a dler clears any.
1d410 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 ** previously se
1d420 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e t handler.)^ ^N
1d430 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 ote that calling
1d440 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 [sqlite3_busy_t
1d450 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 imeout()].** or
1d460 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 evaluating [PRAG
1d470 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d MA busy_timeout=
1d480 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 N] will change t
1d490 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c he.** busy handl
1d4a0 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 er and thus clea
1d4b0 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 r any previously
1d4c0 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 set busy handle
1d4d0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 r..**.** The bus
1d4e0 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c y callback shoul
1d4f0 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 d not take any a
1d500 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 ctions which mod
1d510 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 ify the.** datab
1d520 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
1d530 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
1d540 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 busy handler. I
1d550 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a n other words,.*
1d560 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c * the busy handl
1d570 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 er is not reentr
1d580 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 ant. Any such a
1d590 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 ctions.** result
1d5a0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 in undefined be
1d5b0 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 havior..** .** A
1d5c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 busy handler mu
1d5d0 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 st not close the
1d5e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1d5f0 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 tion.** or [prep
1d600 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
1d610 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
1d620 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
1d630 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 /.int sqlite3_bu
1d640 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 sy_handler(sqlit
1d650 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a e3*,int(*)(void*
1d660 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f ,int),void*);../
1d670 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
1d680 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 et A Busy Timeou
1d690 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
1d6a0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 ite3.**.** ^This
1d6b0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 routine sets a
1d6c0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 [sqlite3_busy_ha
1d6d0 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e ndler | busy han
1d6e0 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 dler] that sleep
1d6f0 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 s.** for a speci
1d700 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 fied amount of t
1d710 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 ime when a table
1d720 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 is locked. ^Th
1d730 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c e handler.** wil
1d740 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 l sleep multiple
1d750 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 times until at
1d760 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 least "ms" milli
1d770 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
1d780 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 ing.** have accu
1d790 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 mulated. ^After
1d7a0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d at least "ms" m
1d7b0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 illiseconds of s
1d7c0 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 leeping,.** the
1d7d0 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 handler returns
1d7e0 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 0 which causes [
1d7f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1d800 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 to return.** [SQ
1d810 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a LITE_BUSY]..**.*
1d820 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 * ^Calling this
1d830 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 routine with an
1d840 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 argument less th
1d850 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a an or equal to z
1d860 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 ero.** turns off
1d870 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 all busy handle
1d880 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 rs..**.** ^(Ther
1d890 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 e can only be a
1d8a0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 single busy hand
1d8b0 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 ler for a partic
1d8c0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 ular.** [databas
1d8d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 e connection] at
1d8e0 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e any given momen
1d8f0 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 t. If another b
1d900 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 usy handler.** w
1d910 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 as defined (usi
1d920 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 ng [sqlite3_busy
1d930 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 _handler()]) pri
1d940 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a or to calling.**
1d950 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 this routine, t
1d960 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 hat other busy h
1d970 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 andler is cleare
1d980 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 d.)^.**.** See a
1d990 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 lso: [PRAGMA bu
1d9a0 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 sy_timeout].*/.i
1d9b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f nt sqlite3_busy_
1d9c0 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a timeout(sqlite3*
1d9d0 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a , int ms);../*.*
1d9e0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 * CAPI3REF: Conv
1d9f0 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 enience Routines
1da00 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 For Running Que
1da10 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ries.** METHOD:
1da20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 sqlite3.**.** Th
1da30 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 is is a legacy i
1da40 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 nterface that is
1da50 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 preserved for b
1da60 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
1da70 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f bility..** Use o
1da80 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 f this interface
1da90 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e is not recommen
1daa0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e ded..**.** Defin
1dab0 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 ition: A <b>resu
1dac0 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 lt table</b> is
1dad0 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 memory data stru
1dae0 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 cture created by
1daf0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
1db00 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e _get_table()] in
1db10 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 terface. A resu
1db20 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 lt table records
1db30 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 the.** complete
1db40 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 query results f
1db50 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 rom one or more
1db60 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 queries..**.** T
1db70 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 he table concept
1db80 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 ually has a numb
1db90 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 er of rows and c
1dba0 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 olumns. But.**
1dbb0 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 these numbers ar
1dbc0 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 e not part of th
1dbd0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 e result table i
1dbe0 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a tself. These.**
1dbf0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 numbers are obt
1dc00 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 ained separately
1dc10 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 . Let N be the
1dc20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a number of rows.*
1dc30 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e * and M be the n
1dc40 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
1dc50 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 ..**.** A result
1dc60 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 table is an arr
1dc70 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 ay of pointers t
1dc80 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 o zero-terminate
1dc90 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e d UTF-8 strings.
1dca0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e .** There are (N
1dcb0 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 +1)*M elements i
1dcc0 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 n the array. Th
1dcd0 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 e first M pointe
1dce0 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a rs point.** to z
1dcf0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
1dd00 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e trings that con
1dd10 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f tain the names o
1dd20 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a f the columns..*
1dd30 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 * The remaining
1dd40 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e entries all poin
1dd50 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c t to query resul
1dd60 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 ts. NULL values
1dd70 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 result.** in NU
1dd80 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c LL pointers. Al
1dd90 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 l other values a
1dda0 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d re in their UTF-
1ddb0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 8 zero-terminate
1ddc0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 d.** string repr
1ddd0 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 esentation as re
1dde0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
1ddf0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
1de00 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c ]..**.** A resul
1de10 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f t table might co
1de20 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 nsist of one or
1de30 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f more memory allo
1de40 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 cations..** It i
1de50 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 s not safe to pa
1de60 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c ss a result tabl
1de70 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 e directly to [s
1de80 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
1de90 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c ** A result tabl
1dea0 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c e should be deal
1deb0 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 located using [s
1dec0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
1ded0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 e()]..**.** ^(As
1dee0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 an example of t
1def0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 he result table
1df00 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 format, suppose
1df10 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a a query result.*
1df20 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a * is as follows:
1df30 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
1df40 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 te><pre>.**
1df50 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c Name |
1df60 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d Age.** -
1df70 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1df80 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 ------.**
1df90 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 Alice | 4
1dfa0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 3.** Bob
1dfb0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 | 28.**
1dfc0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 Cindy
1dfd0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 | 21.** </pre
1dfe0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1dff0 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 *.** There are t
1e000 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 wo column (M==2)
1e010 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 and three rows
1e020 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 (N==3). Thus th
1e030 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c e.** result tabl
1e040 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e e has 8 entries.
1e050 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 Suppose the re
1e060 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 sult table is st
1e070 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 ored.** in an ar
1e080 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 ray names azResu
1e090 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 lt. Then azResu
1e0a0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f lt holds this co
1e0b0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c ntent:.**.** <bl
1e0c0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1e0d0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1e0e0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 t[0] = "Name
1e0f0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1e100 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 esult[1] = "
1e110 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 Age";.**
1e120 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 azResult[2]
1e130 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 = "Alice";.**
1e140 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1e150 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 1;3] = "43";.**
1e160 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
1e170 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a #91;4] = "Bob";.
1e180 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1e190 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 lt[5] = "28"
1e1a0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
1e1b0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 sult[6] = "C
1e1c0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 indy";.**
1e1d0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d azResult[7]
1e1e0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 = "21";.** </pr
1e1f0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 e></blockquote>)
1e200 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ^.**.** ^The sql
1e210 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
1e220 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 function evalua
1e230 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a tes one or more.
1e240 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 ** semicolon-sep
1e250 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 arated SQL state
1e260 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 ments in the zer
1e270 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
1e280 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 -8.** string of
1e290 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 its 2nd paramete
1e2a0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 r and returns a
1e2b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 result table to
1e2c0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 the.** pointer g
1e2d0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 iven in its 3rd
1e2e0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
1e2f0 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 After the appli
1e300 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 cation has finis
1e310 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 hed with the res
1e320 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ult from sqlite3
1e330 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a _get_table(),.**
1e340 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 it must pass th
1e350 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 e result table p
1e360 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ointer to sqlite
1e370 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 3_free_table() i
1e380 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 n order to.** re
1e390 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 lease the memory
1e3a0 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 that was malloc
1e3b0 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 ed. Because of
1e3c0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b the way the.** [
1e3d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1e3e0 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e ] happens within
1e3f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
1e400 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e le(), the callin
1e410 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 g.** function mu
1e420 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 st not try to ca
1e430 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ll [sqlite3_free
1e440 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f ()] directly. O
1e450 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nly.** [sqlite3_
1e460 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 free_table()] is
1e470 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 able to release
1e480 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 the memory prop
1e490 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e erly and safely.
1e4a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
1e4b0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 e3_get_table() i
1e4c0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c nterface is impl
1e4d0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 emented as a wra
1e4e0 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b pper around.** [
1e4f0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e sqlite3_exec()].
1e500 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 The sqlite3_ge
1e510 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e t_table() routin
1e520 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 e does not have
1e530 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 access.** to any
1e540 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 internal data s
1e550 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c tructures of SQL
1e560 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e ite. It uses on
1e570 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a ly the public.**
1e580 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e interface defin
1e590 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 ed here. As a c
1e5a0 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f onsequence, erro
1e5b0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e rs that occur in
1e5c0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 the.** wrapper
1e5d0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 layer outside of
1e5e0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 the internal [s
1e5f0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 qlite3_exec()] c
1e600 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 all are not.** r
1e610 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 eflected in subs
1e620 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
1e630 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
1e640 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
1e650 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f e3_errmsg()]..*/
1e660 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 .int sqlite3_get
1e670 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 _table(. sqlite
1e680 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
1e690 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 /* An open datab
1e6a0 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ase */. const c
1e6b0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f har *zSql, /
1e6c0 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c * SQL to be eval
1e6d0 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 uated */. char
1e6e0 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 ***pazResult,
1e6f0 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 /* Results of t
1e700 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e he query */. in
1e710 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 t *pnRow,
1e720 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 /* Number of
1e730 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 result rows wri
1e740 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 tten here */. i
1e750 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 nt *pnColumn,
1e760 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f /* Number o
1e770 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 f result columns
1e780 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
1e790 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d . char **pzErrm
1e7a0 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f sg /* Erro
1e7b0 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 r msg written he
1e7c0 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 re */.);.void sq
1e7d0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
1e7e0 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b (char **result);
1e7f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1e800 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 : Formatted Stri
1e810 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 ng Printing Func
1e820 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tions.**.** Thes
1e830 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 e routines are w
1e840 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 ork-alikes of th
1e850 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d e "printf()" fam
1e860 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 ily of functions
1e870 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 .** from the sta
1e880 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e ndard C library.
1e890 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
1e8a0 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f es understand mo
1e8b0 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e st of the common
1e8c0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 formatting opti
1e8d0 6f 6e 73 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 ons from.** the
1e8e0 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 standard library
1e8f0 20 70 72 69 6e 74 66 28 29 20 0a 2a 2a 20 70 6c printf() .** pl
1e900 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e us some addition
1e910 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 al non-standard
1e920 66 6f 72 6d 61 74 73 20 28 5b 25 71 5d 2c 20 5b formats ([%q], [
1e930 25 51 5d 2c 20 5b 25 77 5d 2c 20 61 6e 64 20 5b %Q], [%w], and [
1e940 25 7a 5d 29 2e 0a 2a 2a 20 53 65 65 20 74 68 65 %z])..** See the
1e950 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74 [built-in print
1e960 66 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 f()] documentati
1e970 6f 6e 20 66 6f 72 20 64 65 74 61 69 6c 73 2e 0a on for details..
1e980 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1e990 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 e3_mprintf() and
1e9a0 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 sqlite3_vmprint
1e9b0 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 f() routines wri
1e9c0 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 te their.** resu
1e9d0 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 lts into memory
1e9e0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
1e9f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 qlite3_malloc64(
1ea00 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e )]..** The strin
1ea10 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 gs returned by t
1ea20 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 hese two routine
1ea30 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 s should be.** r
1ea40 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 eleased by [sqli
1ea50 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 te3_free()]. ^B
1ea60 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 oth routines ret
1ea70 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f urn a.** NULL po
1ea80 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 inter if [sqlite
1ea90 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 20 69 73 3_malloc64()] is
1eaa0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
1eab0 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 ate enough.** me
1eac0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
1ead0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e resulting strin
1eae0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 g..**.** ^(The s
1eaf0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
1eb00 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d ) routine is sim
1eb10 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 ilar to "snprint
1eb20 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 f()" from.** the
1eb30 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 standard C libr
1eb40 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 ary. The result
1eb50 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f is written into
1eb60 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 the.** buffer s
1eb70 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 upplied as the s
1eb80 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1eb90 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 whose size is gi
1eba0 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 ven by.** the fi
1ebb0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e rst parameter. N
1ebc0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 ote that the ord
1ebd0 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 er of the.** fir
1ebe0 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 st two parameter
1ebf0 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 s is reversed fr
1ec00 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e om snprintf().)^
1ec10 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 This is an.**
1ec20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 historical accid
1ec30 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 ent that cannot
1ec40 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 be fixed without
1ec50 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 breaking.** bac
1ec60 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
1ec70 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c lity. ^(Note al
1ec80 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f so that sqlite3_
1ec90 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 snprintf().** re
1eca0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
1ecb0 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e to its buffer in
1ecc0 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d stead of the num
1ecd0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 ber of.** charac
1ece0 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 ters actually wr
1ecf0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 itten into the b
1ed00 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d uffer.)^ We adm
1ed10 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e it that.** the n
1ed20 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 umber of charact
1ed30 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c ers written woul
1ed40 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 d be a more usef
1ed50 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c ul return.** val
1ed60 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 ue but we cannot
1ed70 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c change the impl
1ed80 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 ementation of sq
1ed90 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
1eda0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 .** now without
1edb0 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 breaking compati
1edc0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 bility..**.** ^A
1edd0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 s long as the bu
1ede0 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 ffer size is gre
1edf0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 ater than zero,
1ee00 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
1ee10 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 ().** guarantees
1ee20 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 that the buffer
1ee30 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d is always zero-
1ee40 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 terminated. ^Th
1ee50 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d e first.** param
1ee60 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 eter "n" is the
1ee70 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 total size of th
1ee80 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 e buffer, includ
1ee90 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a ing space for.**
1eea0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e the zero termin
1eeb0 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f ator. So the lo
1eec0 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 ngest string tha
1eed0 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 t can be complet
1eee0 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 ely.** written w
1eef0 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 ill be n-1 chara
1ef00 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 cters..**.** ^Th
1ef10 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 e sqlite3_vsnpri
1ef20 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ntf() routine is
1ef30 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 a varargs versi
1ef40 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e on of sqlite3_sn
1ef50 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 printf()..**.**
1ef60 53 65 65 20 61 6c 73 6f 3a 20 20 5b 62 75 69 6c See also: [buil
1ef70 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d 2c 20 t-in printf()],
1ef80 5b 70 72 69 6e 74 66 28 29 20 53 51 4c 20 66 75 [printf() SQL fu
1ef90 6e 63 74 69 6f 6e 5d 0a 2a 2f 0a 63 68 61 72 20 nction].*/.char
1efa0 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 *sqlite3_mprintf
1efb0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e (const char*,...
1efc0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 );.char *sqlite3
1efd0 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 _vmprintf(const
1efe0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b char*, va_list);
1eff0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 .char *sqlite3_s
1f000 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 nprintf(int,char
1f010 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e *,const char*, .
1f020 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 ..);.char *sqlit
1f030 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 e3_vsnprintf(int
1f040 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 ,char*,const cha
1f050 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f r*, va_list);../
1f060 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
1f070 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e emory Allocation
1f080 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a Subsystem.**.**
1f090 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
1f0a0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 uses these thre
1f0b0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 e routines for a
1f0c0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a ll of its own.**
1f0d0 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 internal memory
1f0e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 allocation need
1f0f0 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 s. "Core" in the
1f100 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e previous senten
1f110 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 ce.** does not i
1f120 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 nclude operating
1f130 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 -system specific
1f140 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
1f150 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e ion. The.** Win
1f160 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 dows VFS uses na
1f170 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e tive malloc() an
1f180 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d d free() for som
1f190 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a e operations..**
1f1a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1f1b0 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e _malloc() routin
1f1c0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
1f1d0 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a ter to a block.*
1f1e0 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c * of memory at l
1f1f0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 east N bytes in
1f200 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 length, where N
1f210 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 is the parameter
1f220 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 ..** ^If sqlite3
1f230 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 _malloc() is una
1f240 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 ble to obtain su
1f250 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a fficient free.**
1f260 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 memory, it retu
1f270 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
1f280 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 er. ^If the par
1f290 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 ameter N to.** s
1f2a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
1f2b0 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 is zero or negat
1f2c0 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ive then sqlite3
1f2d0 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e _malloc() return
1f2e0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e s.** a NULL poin
1f2f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
1f300 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 sqlite3_malloc64
1f310 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b (N) routine work
1f320 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 s just like.** s
1f330 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 qlite3_malloc(N)
1f340 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 except that N i
1f350 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 s an unsigned 64
1f360 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 -bit integer ins
1f370 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 tead.** of a sig
1f380 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 ned 32-bit integ
1f390 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 er..**.** ^Calli
1f3a0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 ng sqlite3_free(
1f3b0 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 ) with a pointer
1f3c0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 previously retu
1f3d0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 rned.** by sqlit
1f3e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 e3_malloc() or s
1f3f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1f400 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d releases that m
1f410 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 emory so.** that
1f420 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 it might be reu
1f430 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 sed. ^The sqlit
1f440 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e e3_free() routin
1f450 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 e is.** a no-op
1f460 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 if is called wit
1f470 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 h a NULL pointer
1f480 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c . Passing a NUL
1f490 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 L pointer.** to
1f4a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 sqlite3_free() i
1f4b0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 s harmless. Aft
1f4c0 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 er being freed,
1f4d0 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 memory.** should
1f4e0 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 neither be read
1f4f0 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 nor written. E
1f500 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 ven reading prev
1f510 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 iously freed.**
1f520 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 memory might res
1f530 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 ult in a segment
1f540 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f ation fault or o
1f550 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f ther severe erro
1f560 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 r..** Memory cor
1f570 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 ruption, a segme
1f580 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f ntation fault, o
1f590 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 r other severe e
1f5a0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 rror.** might re
1f5b0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f sult if sqlite3_
1f5c0 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 free() is called
1f5d0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c with a non-NULL
1f5e0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a pointer that.**
1f5f0 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 was not obtaine
1f600 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d d from sqlite3_m
1f610 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 alloc() or sqlit
1f620 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a e3_realloc()..**
1f630 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1f640 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e _realloc(X,N) in
1f650 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 terface attempts
1f660 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 to resize a.**
1f670 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c prior memory all
1f680 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 ocation X to be
1f690 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 at least N bytes
1f6a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 ..** ^If the X p
1f6b0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
1f6c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
1f6d0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f .** is a NULL po
1f6e0 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 inter then its b
1f6f0 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 ehavior is ident
1f700 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a ical to calling.
1f710 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f ** sqlite3_mallo
1f720 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 c(N)..** ^If the
1f730 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 N parameter to
1f740 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1f750 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a X,N) is zero or.
1f760 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e ** negative then
1f770 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
1f780 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d exactly the sam
1f790 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 e as calling.**
1f7a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e sqlite3_free(X).
1f7b0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 .** ^sqlite3_rea
1f7c0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e lloc(X,N) return
1f7d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
1f7e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1f7f0 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 on.** of at leas
1f800 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a t N bytes in siz
1f810 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 e or NULL if ins
1f820 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 ufficient memory
1f830 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a is available..*
1f840 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 * ^If M is the s
1f850 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 ize of the prior
1f860 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 allocation, the
1f870 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 n min(N,M) bytes
1f880 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 .** of the prior
1f890 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 allocation are
1f8a0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 copied into the
1f8b0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 beginning of buf
1f8c0 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 fer returned.**
1f8d0 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c by sqlite3_reall
1f8e0 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 oc(X,N) and the
1f8f0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
1f900 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 is freed..** ^I
1f910 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f f sqlite3_reallo
1f920 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e c(X,N) returns N
1f930 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 ULL and N is pos
1f940 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a itive, then the.
1f950 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 ** prior allocat
1f960 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 ion is not freed
1f970 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
1f980 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 ite3_realloc64(X
1f990 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 ,N) interfaces w
1f9a0 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 orks the same as
1f9b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c .** sqlite3_real
1f9c0 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 loc(X,N) except
1f9d0 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 that N is a 64-b
1f9e0 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 it unsigned inte
1f9f0 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f ger instead.** o
1fa00 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 f a 32-bit signe
1fa10 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a d integer..**.**
1fa20 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f ^If X is a memo
1fa30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 ry allocation pr
1fa40 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 eviously obtaine
1fa50 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d d from sqlite3_m
1fa60 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 alloc(),.** sqli
1fa70 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 te3_malloc64(),
1fa80 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1fa90 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ), or sqlite3_re
1faa0 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a alloc64(), then.
1fab0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 ** sqlite3_msize
1fac0 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 (X) returns the
1fad0 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d size of that mem
1fae0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 ory allocation i
1faf0 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 n bytes..** ^The
1fb00 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
1fb10 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 by sqlite3_msize
1fb20 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 (X) might be lar
1fb30 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d ger than the num
1fb40 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 ber.** of bytes
1fb50 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 requested when X
1fb60 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 was allocated.
1fb70 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c ^If X is a NULL
1fb80 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a pointer then.**
1fb90 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 sqlite3_msize(X
1fba0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 ) returns zero.
1fbb0 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 If X points to
1fbc0 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 something that i
1fbd0 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 s not.** the beg
1fbe0 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 inning of memory
1fbf0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 allocation, or
1fc00 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 if it points to
1fc10 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 a formerly.** va
1fc20 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 lid memory alloc
1fc30 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e ation that has n
1fc40 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 ow been freed, t
1fc50 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
1fc60 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d .** of sqlite3_m
1fc70 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 size(X) is undef
1fc80 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c ined and possibl
1fc90 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a y harmful..**.**
1fca0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 ^The memory ret
1fcb0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
1fcc0 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 _malloc(), sqlit
1fcd0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a e3_realloc(),.**
1fce0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 sqlite3_malloc6
1fcf0 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 4(), and sqlite3
1fd00 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 _realloc64().**
1fd10 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 is always aligne
1fd20 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e d to at least an
1fd30 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 8 byte boundary
1fd40 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 , or to a.** 4 b
1fd50 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 yte boundary if
1fd60 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 the [SQLITE_4_BY
1fd70 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f TE_ALIGNED_MALLO
1fd80 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a C] compile-time.
1fd90 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 ** option is use
1fda0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 d..**.** In SQLi
1fdb0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 te version 3.5.0
1fdc0 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 and 3.5.1, it w
1fdd0 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 as possible to d
1fde0 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c efine.** the SQL
1fdf0 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f ITE_OMIT_MEMORY_
1fe00 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 ALLOCATION which
1fe10 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 would cause the
1fe20 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 built-in.** imp
1fe30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
1fe40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f hese routines to
1fe50 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 be omitted. Th
1fe60 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a at capability.**
1fe70 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 is no longer pr
1fe80 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 ovided. Only bu
1fe90 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c ilt-in memory al
1fea0 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 locators can be
1feb0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f used..**.** Prio
1fec0 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 r to SQLite vers
1fed0 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 ion 3.7.10, the
1fee0 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 Windows OS inter
1fef0 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 face layer calle
1ff00 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 d.** the system
1ff10 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 malloc() and fre
1ff20 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 e() directly whe
1ff30 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 n converting.**
1ff40 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 filenames betwee
1ff50 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f n the UTF-8 enco
1ff60 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c ding used by SQL
1ff70 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 ite.** and whate
1ff80 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 ver filename enc
1ff90 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 oding is used by
1ffa0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 the particular
1ffb0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 Windows.** insta
1ffc0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 llation. Memory
1ffd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f allocation erro
1ffe0 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 rs were detected
1fff0 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 , but.** they we
20000 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b re reported back
20010 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 as [SQLITE_CANT
20020 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c OPEN] or.** [SQL
20030 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 ITE_IOERR] rathe
20040 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e r than [SQLITE_N
20050 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 OMEM]..**.** The
20060 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e pointer argumen
20070 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 ts to [sqlite3_f
20080 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ree()] and [sqli
20090 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a te3_realloc()].*
200a0 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 * must be either
200b0 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f NULL or else po
200c0 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 inters obtained
200d0 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 from a prior.**
200e0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 invocation of [s
200f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
20100 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
20110 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 lloc()] that hav
20120 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 e.** not yet bee
20130 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a n released..**.*
20140 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
20150 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 n must not read
20160 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 or write any par
20170 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 t of.** a block
20180 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 of memory after
20190 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 it has been rele
201a0 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 ased using.** [s
201b0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f qlite3_free()] o
201c0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c r [sqlite3_reall
201d0 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a oc()]..*/.void *
201e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 sqlite3_malloc(i
201f0 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 nt);.void *sqlit
20200 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 e3_malloc64(sqli
20210 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 te3_uint64);.voi
20220 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c d *sqlite3_reall
20230 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a oc(void*, int);.
20240 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 void *sqlite3_re
20250 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 alloc64(void*, s
20260 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a qlite3_uint64);.
20270 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 void sqlite3_fre
20280 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 e(void*);.sqlite
20290 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 3_uint64 sqlite3
202a0 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a _msize(void*);..
202b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
202c0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 Memory Allocator
202d0 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a Statistics.**.*
202e0 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 * SQLite provide
202f0 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 s these two inte
20300 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 rfaces for repor
20310 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 ting on the stat
20320 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 us.** of the [sq
20330 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c lite3_malloc()],
20340 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
20350 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
20360 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f realloc()].** ro
20370 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f utines, which fo
20380 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 rm the built-in
20390 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
203a0 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a n subsystem..**.
203b0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
203c0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 _memory_used()]
203d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
203e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
203f0 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 tes.** of memory
20400 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 currently outst
20410 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 anding (malloced
20420 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e but not freed).
20430 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 .** ^The [sqlite
20440 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
20450 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 er()] routine re
20460 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 turns the maximu
20470 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 m.** value of [s
20480 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
20490 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 ed()] since the
204a0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a high-water mark.
204b0 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 ** was last rese
204c0 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 t. ^The values
204d0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
204e0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
204f0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 ()] and.** [sqli
20500 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
20510 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 ater()] include
20520 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 any overhead.**
20530 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 added by SQLite
20540 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 in its implement
20550 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 ation of [sqlite
20560 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 3_malloc()],.**
20570 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 but not overhead
20580 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e added by the an
20590 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 y underlying sys
205a0 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 tem library.** r
205b0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 outines that [sq
205c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
205d0 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 may call..**.**
205e0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 ^The memory high
205f0 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 -water mark is r
20600 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 eset to the curr
20610 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 ent value of.**
20620 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
20630 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f used()] if and o
20640 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d nly if the param
20650 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 eter to.** [sqli
20660 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
20670 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e ater()] is true.
20680 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 ^The value ret
20690 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c urned.** by [sql
206a0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
206b0 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 water(1)] is the
206c0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b high-water mark
206d0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 .** prior to the
206e0 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 reset..*/.sqlit
206f0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
20700 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 _memory_used(voi
20710 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 d);.sqlite3_int6
20720 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 4 sqlite3_memory
20730 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 _highwater(int r
20740 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a esetFlag);../*.*
20750 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 * CAPI3REF: Pseu
20760 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 do-Random Number
20770 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a Generator.**.**
20780 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 SQLite contains
20790 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 a high-quality
207a0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 pseudo-random nu
207b0 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 mber generator (
207c0 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a PRNG) used to.**
207d0 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b select random [
207e0 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 ROWID | ROWIDs]
207f0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e when inserting n
20800 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 ew records into
20810 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 a table that.**
20820 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 already uses the
20830 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c largest possibl
20840 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 e [ROWID]. The
20850 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 PRNG is also use
20860 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 d for.** the bui
20870 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 ld-in random() a
20880 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 nd randomblob()
20890 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 SQL functions.
208a0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 This interface a
208b0 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 llows.** applica
208c0 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 tions to access
208d0 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f the same PRNG fo
208e0 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 r other purposes
208f0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 ..**.** ^A call
20900 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 to this routine
20910 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f stores N bytes o
20920 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 f randomness int
20930 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e o buffer P..** ^
20940 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 The P parameter
20950 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f can be a NULL po
20960 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 inter..**.** ^If
20970 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 this routine ha
20980 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 s not been previ
20990 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 ously called or
209a0 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a if the previous.
209b0 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 ** call had N le
209c0 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 ss than one or a
209d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f NULL pointer fo
209e0 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 r P, then the PR
209f0 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 NG is.** seeded
20a00 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 using randomness
20a10 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 obtained from t
20a20 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d he xRandomness m
20a30 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 ethod of.** the
20a40 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
20a50 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a _vfs] object..**
20a60 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 ^If the previou
20a70 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 s call to this r
20a80 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 outine had an N
20a90 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 of 1 or more and
20aa0 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 a.** non-NULL P
20ab0 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f then the pseudo
20ac0 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 -randomness is g
20ad0 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 enerated.** inte
20ae0 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f rnally and witho
20af0 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 ut recourse to t
20b00 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d he [sqlite3_vfs]
20b10 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 xRandomness.**
20b20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 method..*/.void
20b30 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 sqlite3_randomne
20b40 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a ss(int N, void *
20b50 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 P);../*.** CAPI3
20b60 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d REF: Compile-Tim
20b70 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 e Authorization
20b80 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 Callbacks.** MET
20b90 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 HOD: sqlite3.**
20ba0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f KEYWORDS: {autho
20bb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a rizer callback}.
20bc0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
20bd0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e ine registers an
20be0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
20bf0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 back with a part
20c00 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
20c10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c ase connection],
20c20 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 supplied in the
20c30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e first argument.
20c40 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 .** ^The authori
20c50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
20c60 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 invoked as SQL s
20c70 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 tatements are be
20c80 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 ing compiled.**
20c90 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 by [sqlite3_prep
20ca0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 are()] or its va
20cb0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f riants [sqlite3_
20cc0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a prepare_v2()],.*
20cd0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
20ce0 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 re_v3()], [sqlit
20cf0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c e3_prepare16()],
20d00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
20d10 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e e16_v2()],.** an
20d20 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
20d30 72 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 re16_v3()]. ^At
20d40 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e various.** poin
20d50 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f ts during the co
20d60 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 mpilation proces
20d70 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 s, as logic is b
20d80 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 eing created.**
20d90 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f to perform vario
20da0 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 us actions, the
20db0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
20dc0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 ack is invoked t
20dd0 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 o.** see if thos
20de0 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c e actions are al
20df0 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 lowed. ^The aut
20e00 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
20e10 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 should.** retur
20e20 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f n [SQLITE_OK] to
20e30 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f allow the actio
20e40 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 n, [SQLITE_IGNOR
20e50 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 E] to disallow t
20e60 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 he.** specific a
20e70 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 ction but allow
20e80 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
20e90 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f t to continue to
20ea0 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c be.** compiled,
20eb0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 or [SQLITE_DENY
20ec0 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 ] to cause the e
20ed0 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d ntire SQL statem
20ee0 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a ent to be.** rej
20ef0 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 ected with an er
20f00 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 ror. ^If the au
20f10 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
20f20 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 k returns.** any
20f30 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 value other tha
20f40 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 n [SQLITE_IGNORE
20f50 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 ], [SQLITE_OK],
20f60 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d or [SQLITE_DENY]
20f70 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 .** then the [sq
20f80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
20f90 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e ()] or equivalen
20fa0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 t call that trig
20fb0 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 gered.** the aut
20fc0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 horizer will fai
20fd0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 l with an error
20fe0 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 message..**.** W
20ff0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
21000 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
21010 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 _OK], that means
21020 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a the operation.*
21030 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f * requested is o
21040 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 k. ^When the ca
21050 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
21060 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 SQLITE_DENY], th
21070 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 e.** [sqlite3_pr
21080 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 epare_v2()] or e
21090 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 quivalent call t
210a0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 hat triggered th
210b0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 e.** authorizer
210c0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 will fail with a
210d0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 n error message
210e0 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a explaining that.
210f0 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e ** access is den
21100 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ied. .**.** ^The
21110 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
21120 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
21130 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 er callback is a
21140 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 copy of the thi
21150 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 rd.** parameter
21160 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 to the sqlite3_s
21170 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 et_authorizer()
21180 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 interface. ^The
21190 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
211a0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 .** to the callb
211b0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ack is an intege
211c0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c r [SQLITE_COPY |
211d0 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 action code] th
211e0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 at specifies.**
211f0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 the particular a
21200 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 ction to be auth
21210 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 orized. ^The thi
21220 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 rd through sixth
21230 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 parameters.** t
21240 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 o the callback a
21250 72 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 re either NULL p
21260 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d ointers or zero-
21270 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e terminated strin
21280 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 gs.** that conta
21290 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 in additional de
212a0 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 tails about the
212b0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 action to be aut
212c0 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c horized..** Appl
212d0 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c ications must al
212e0 77 61 79 73 20 62 65 20 70 72 65 70 61 72 65 64 ways be prepared
212f0 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 to encounter a
21300 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 NULL pointer in
21310 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 any.** of the th
21320 69 72 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 ird through the
21330 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 sixth parameters
21340 20 6f 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a of the authoriz
21350 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a ation callback..
21360 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 **.** ^If the ac
21370 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 tion code is [SQ
21380 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e LITE_READ].** an
21390 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 d the callback r
213a0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 eturns [SQLITE_I
213b0 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a GNORE] then the.
213c0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
213d0 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e tement] statemen
213e0 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 t is constructed
213f0 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a to substitute.*
21400 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 * a NULL value i
21410 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 n place of the t
21420 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 able column that
21430 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 would have.** b
21440 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c een read if [SQL
21450 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e ITE_OK] had been
21460 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 returned. The
21470 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a [SQLITE_IGNORE].
21480 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 ** return can be
21490 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e used to deny an
214a0 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 untrusted user
214b0 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 access to indivi
214c0 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 dual.** columns
214d0 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e of a table..** ^
214e0 57 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 When a table is
214f0 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 61 20 referenced by a
21500 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 [SELECT] but no
21510 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 column values ar
21520 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66 e.** extracted f
21530 72 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28 rom that table (
21540 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 for example in a
21550 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 query like.** "
21560 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 SELECT count(*)
21570 46 52 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20 FROM tab") then
21580 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 the [SQLITE_READ
21590 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c ] authorizer cal
215a0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f lback.** is invo
215b0 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 ked once for tha
215c0 74 20 74 61 62 6c 65 20 77 69 74 68 20 61 20 63 t table with a c
215d0 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 olumn name that
215e0 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 is an empty stri
215f0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 ng..** ^If the a
21600 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 ction code is [S
21610 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e QLITE_DELETE] an
21620 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 d the callback r
21630 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 eturns.** [SQLIT
21640 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 E_IGNORE] then t
21650 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 he [DELETE] oper
21660 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 ation proceeds b
21670 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 ut the.** [trunc
21680 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e ate optimization
21690 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e ] is disabled an
216a0 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 d all rows are d
216b0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 eleted individua
216c0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 lly..**.** An au
216d0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 thorizer is used
216e0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 when [sqlite3_p
216f0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 repare | prepari
21700 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ng].** SQL state
21710 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e ments from an un
21720 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 trusted source,
21730 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 to ensure that t
21740 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
21750 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 s.** do not try
21760 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 to access data t
21770 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f hey are not allo
21780 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 wed to see, or t
21790 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a hat they do not.
217a0 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 ** try to execut
217b0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 e malicious stat
217c0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 ements that dama
217d0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e ge the database.
217e0 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 For.** example
217f0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
21800 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 may allow a use
21810 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 r to enter arbit
21820 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 rary.** SQL quer
21830 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 ies for evaluati
21840 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 on by a database
21850 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 . But the appli
21860 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e cation does.** n
21870 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 ot want the user
21880 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d to be able to m
21890 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 ake arbitrary ch
218a0 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 anges to the.**
218b0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 database. An au
218c0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 thorizer could t
218d0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c hen be put in pl
218e0 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a ace while the.**
218f0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 user-entered SQ
21900 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 L is being [sqli
21910 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 te3_prepare | pr
21920 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 epared] that.**
21930 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 disallows everyt
21940 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c hing except [SEL
21950 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e ECT] statements.
21960 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
21970 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f ons that need to
21980 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f process SQL fro
21990 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 m untrusted sour
219a0 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 ces.** might als
219b0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 o consider lower
219c0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d ing resource lim
219d0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 its using [sqlit
219e0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 e3_limit()].** a
219f0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 nd limiting data
21a00 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 base size using
21a10 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f the [max_page_co
21a20 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a unt] [PRAGMA].**
21a30 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 in addition to
21a40 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 using an authori
21a50 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c zer..**.** ^(Onl
21a60 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f y a single autho
21a70 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 rizer can be in
21a80 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 place on a datab
21a90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
21aa0 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 * at a time. Ea
21ab0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ch call to sqlit
21ac0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
21ad0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a r overrides the.
21ae0 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c ** previous call
21af0 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 .)^ ^Disable th
21b00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 e authorizer by
21b10 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c installing a NUL
21b20 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 L callback..** T
21b30 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 he authorizer is
21b40 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
21b50 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ault..**.** The
21b60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
21b70 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ack must not do
21b80 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
21b90 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
21ba0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
21bb0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
21bc0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 d the authorizer
21bd0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f callback..** No
21be0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 te that [sqlite3
21bf0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
21c00 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 nd [sqlite3_step
21c10 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 ()] both modify
21c20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 their.** databas
21c30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f e connections fo
21c40 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 r the meaning of
21c50 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 "modify" in thi
21c60 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a s paragraph..**.
21c70 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 ** ^When [sqlite
21c80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
21c90 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 is used to prepa
21ca0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 re a statement,
21cb0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 the.** statement
21cc0 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 might be re-pre
21cd0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 pared during [sq
21ce0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 lite3_step()] du
21cf0 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d e to a .** schem
21d00 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 a change. Hence
21d10 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f , the applicatio
21d20 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 n should ensure
21d30 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 that the.** corr
21d40 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 ect authorizer c
21d50 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 allback remains
21d60 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 in place during
21d70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 the [sqlite3_ste
21d80 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 p()]..**.** ^Not
21d90 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f e that the autho
21da0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
21db0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 s invoked only d
21dc0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 uring.** [sqlite
21dd0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
21de0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 its variants. A
21df0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 uthorization is
21e00 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 not.** performed
21e10 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e during statemen
21e20 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 t evaluation in
21e30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
21e40 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 , unless.** as s
21e50 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 tated in the pre
21e60 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c vious paragraph,
21e70 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
21e80 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 invokes.** sqlit
21e90 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 e3_prepare_v2()
21ea0 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 to reprepare a s
21eb0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 tatement after a
21ec0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a schema change..
21ed0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 */.int sqlite3_s
21ee0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 et_authorizer(.
21ef0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 sqlite3*,. int
21f00 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c (*xAuth)(void*,
21f10 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c int,const char*,
21f20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
21f30 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
21f40 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 ar*),. void *pU
21f50 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a serData.);../*.*
21f60 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 * CAPI3REF: Auth
21f70 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f orizer Return Co
21f80 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 des.**.** The [s
21f90 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
21fa0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
21fb0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
21fc0 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 tion] must.** re
21fd0 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c turn either [SQL
21fe0 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f ITE_OK] or one o
21ff0 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 f these two cons
22000 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a tants in order.*
22010 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 * to signal SQLi
22020 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f te whether or no
22030 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 t the action is
22040 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 permitted. See
22050 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
22060 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
22070 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 authorizer docu
22080 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 mentation] for a
22090 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
220a0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
220b0 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 Note that SQLITE
220c0 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 _IGNORE is also
220d0 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c used as a [confl
220e0 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d ict resolution m
220f0 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 ode].** returned
22100 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 from the [sqlit
22110 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c e3_vtab_on_confl
22120 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ict()] interface
22130 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
22140 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f ITE_DENY 1 /
22150 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 * Abort the SQL
22160 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 statement with a
22170 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 n error */.#defi
22180 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 ne SQLITE_IGNORE
22190 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 2 /* Don't al
221a0 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 low access, but
221b0 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 don't generate a
221c0 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a n error */../*.*
221d0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 * CAPI3REF: Auth
221e0 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f orizer Action Co
221f0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 des.**.** The [s
22200 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
22210 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 rizer()] interfa
22220 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 ce registers a c
22230 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
22240 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f .** that is invo
22250 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 ked to authorize
22260 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 certain SQL sta
22270 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 tement actions.
22280 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 The.** second p
22290 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
222a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 callback is an i
222b0 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 nteger code that
222c0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 specifies.** wh
222d0 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 at action is bei
222e0 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 ng authorized.
222f0 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e These are the in
22300 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 teger action cod
22310 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 es that.** the a
22320 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
22330 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 ck may be passed
22340 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 ..**.** These ac
22350 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 tion code values
22360 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 signify what ki
22370 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 nd of operation
22380 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 is to be.** auth
22390 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 orized. The 3rd
223a0 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 and 4th paramet
223b0 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f ers to the autho
223c0 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c rization.** call
223d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 back function wi
223e0 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 ll be parameters
223f0 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 or NULL dependi
22400 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 ng on which of t
22410 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 hese.** codes is
22420 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 used as the sec
22430 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 ond parameter.
22440 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 ^(The 5th parame
22450 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 ter to the.** au
22460 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
22470 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 k is the name of
22480 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 the database ("
22490 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a main", "temp",.*
224a0 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 * etc.) if appli
224b0 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 cable.)^ ^The 6
224c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
224d0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
224e0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 allback.** is th
224f0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e e name of the in
22500 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 ner-most trigger
22510 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 or view that is
22520 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
22530 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 .** the access a
22540 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 ttempt or NULL i
22550 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 f this access at
22560 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c tempt is directl
22570 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 y from.** top-le
22580 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f vel SQL code..*/
22590 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ./**************
225a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
225b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 ************* 3r
225c0 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 d ************ 4
225d0 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a th ***********/.
225e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
225f0 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 REATE_INDEX
22600 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 1 /* Inde
22610 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
22620 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
22630 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
22640 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 EATE_TABLE
22650 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 2 /* Table
22660 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
22670 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
22680 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
22690 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 ATE_TEMP_INDEX
226a0 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 3 /* Index
226b0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
226c0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
226d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
226e0 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 TE_TEMP_TABLE
226f0 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 4 /* Table N
22700 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
22710 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
22720 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
22730 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 E_TEMP_TRIGGER
22740 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 5 /* Trigger
22750 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
22760 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
22770 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
22780 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 _TEMP_VIEW
22790 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 6 /* View Name
227a0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
227b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
227c0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
227d0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 TRIGGER 7
227e0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
227f0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
22800 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
22810 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 SQLITE_CREATE_V
22820 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 IEW 8
22830 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
22840 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
22850 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22860 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 SQLITE_DELETE
22870 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 9
22880 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
22890 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
228a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
228b0 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 QLITE_DROP_INDEX
228c0 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 10
228d0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
228e0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
228f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
22900 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 LITE_DROP_TABLE
22910 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 11 /
22920 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
22930 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
22940 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22950 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e ITE_DROP_TEMP_IN
22960 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a DEX 12 /*
22970 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
22980 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
22990 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
229a0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 TE_DROP_TEMP_TAB
229b0 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 LE 13 /*
229c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
229d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
229e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
229f0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 E_DROP_TEMP_TRIG
22a00 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 GER 14 /* T
22a10 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
22a20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
22a30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22a40 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 _DROP_TEMP_VIEW
22a50 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 15 /* Vi
22a60 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
22a70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
22a80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22a90 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 DROP_TRIGGER
22aa0 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 16 /* Tri
22ab0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
22ac0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
22ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
22ae0 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 ROP_VIEW
22af0 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 17 /* View
22b00 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
22b10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
22b20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
22b30 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 SERT
22b40 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 18 /* Table
22b50 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
22b60 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
22b70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 efine SQLITE_PRA
22b80 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 GMA
22b90 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 19 /* Pragma
22ba0 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 Name 1st ar
22bb0 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 g or NULL */.#de
22bc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
22bd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
22be0 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 20 /* Table N
22bf0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 ame Column
22c00 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
22c10 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 ine SQLITE_SELEC
22c20 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
22c30 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 21 /* NULL
22c40 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 NULL
22c50 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
22c60 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 ne SQLITE_TRANSA
22c70 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 CTION 2
22c80 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 2 /* Operation
22c90 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
22ca0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
22cb0 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 e SQLITE_UPDATE
22cc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 23
22cd0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
22ce0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d Column Nam
22cf0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
22d00 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 SQLITE_ATTACH
22d10 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 24
22d20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 /* Filename
22d30 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
22d40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22d50 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 SQLITE_DETACH
22d60 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 25
22d70 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d /* Database Nam
22d80 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 e NULL
22d90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
22da0 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c QLITE_ALTER_TABL
22db0 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 E 26
22dc0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 /* Database Name
22dd0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
22de0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
22df0 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 LITE_REINDEX
22e00 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 27 /
22e10 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
22e20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
22e30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22e40 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 ITE_ANALYZE
22e50 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 28 /*
22e60 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
22e70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
22e80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22e90 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 TE_CREATE_VTABLE
22ea0 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 29 /*
22eb0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
22ec0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 Module Name
22ed0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
22ee0 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 E_DROP_VTABLE
22ef0 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 30 /* T
22f00 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d able Name M
22f10 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a odule Name *
22f20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22f30 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 _FUNCTION
22f40 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 31 /* NU
22f50 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 LL Fu
22f60 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f nction Name */
22f70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22f80 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 SAVEPOINT
22f90 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 32 /* Ope
22fa0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 ration Sav
22fb0 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a epoint Name */.
22fc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
22fd0 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 OPY
22fe0 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 0 /* No l
22ff0 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 onger used */.#d
23000 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 efine SQLITE_REC
23010 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20 URSIVE
23020 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 33 /* NULL
23030 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 NULL
23040 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a */../*
23050 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 .** CAPI3REF: Tr
23060 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c acing And Profil
23070 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a ing Functions.**
23080 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
23090 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
230a0 74 69 6e 65 73 20 61 72 65 20 64 65 70 72 65 63 tines are deprec
230b0 61 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 ated. Use the [s
230c0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 qlite3_trace_v2(
230d0 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 )] interface.**
230e0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 72 instead of the r
230f0 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65 outines describe
23100 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 d here..**.** Th
23110 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 ese routines reg
23120 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 ister callback f
23130 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 unctions that ca
23140 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a n be used for.**
23150 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f tracing and pro
23160 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 filing the execu
23170 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 tion of SQL stat
23180 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ements..**.** ^T
23190 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
231a0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 tion registered
231b0 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 by sqlite3_trace
231c0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 () is invoked at
231d0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 .** various time
231e0 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 s when an SQL st
231f0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 atement is being
23200 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 run by [sqlite3
23210 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 _step()]..** ^Th
23220 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 e sqlite3_trace(
23230 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e ) callback is in
23240 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 voked with a UTF
23250 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 -8 rendering of
23260 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 the.** SQL state
23270 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 ment text as the
23280 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 statement first
23290 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e begins executin
232a0 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e g..** ^(Addition
232b0 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 al sqlite3_trace
232c0 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 () callbacks mig
232d0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 ht occur.** as e
232e0 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 ach triggered su
232f0 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 bprogram is ente
23300 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 red. The callba
23310 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 cks for triggers
23320 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 .** contain a UT
23330 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 F-8 SQL comment
23340 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 that identifies
23350 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a the trigger.)^.*
23360 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 *.** The [SQLITE
23370 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 _TRACE_SIZE_LIMI
23380 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 T] compile-time
23390 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 option can be us
233a0 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 ed to limit.** t
233b0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f he length of [bo
233c0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 und parameter] e
233d0 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 xpansion in the
233e0 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 output of sqlite
233f0 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 3_trace()..**.**
23400 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 ^The callback f
23410 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
23420 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 ed by sqlite3_pr
23430 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b ofile() is invok
23440 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 ed.** as each SQ
23450 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 L statement fini
23460 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 shes. ^The prof
23470 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e ile callback con
23480 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 tains.** the ori
23490 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 ginal statement
234a0 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 text and an esti
234b0 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f mate of wall-clo
234c0 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f ck time.** of ho
234d0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 w long that stat
234e0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 ement took to ru
234f0 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 n. ^The profile
23500 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d callback.** tim
23510 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 e is in units of
23520 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f nanoseconds, ho
23530 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e wever the curren
23540 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e t implementation
23550 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 .** is only capa
23560 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f ble of milliseco
23570 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f nd resolution so
23580 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 the six least s
23590 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 ignificant.** di
235a0 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 gits in the time
235b0 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 are meaningless
235c0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
235d0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 ns of SQLite.**
235e0 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 might provide gr
235f0 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e eater resolution
23600 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 on the profiler
23610 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a callback. The.
23620 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 ** sqlite3_profi
23630 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 le() function is
23640 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 considered expe
23650 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a rimental and is.
23660 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 ** subject to ch
23670 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 ange in future v
23680 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
23690 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 e..*/.SQLITE_DEP
236a0 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 RECATED void *sq
236b0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 lite3_trace(sqli
236c0 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 te3*,. void(*x
236d0 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e Trace)(void*,con
236e0 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a st char*), void*
236f0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 );.SQLITE_DEPREC
23700 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 ATED void *sqlit
23710 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 e3_profile(sqlit
23720 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 e3*,. void(*xP
23730 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f rofile)(void*,co
23740 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 nst char*,sqlite
23750 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 3_uint64), void*
23760 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
23770 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76 EF: SQL Trace Ev
23780 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 ent Codes.** KEY
23790 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 WORDS: SQLITE_TR
237a0 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ACE.**.** These
237b0 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69 constants identi
237c0 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76 fy classes of ev
237d0 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62 65 ents that can be
237e0 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 monitored.** us
237f0 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ing the [sqlite3
23800 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61 _trace_v2()] tra
23810 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 cing logic. The
23820 20 4d 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 M argument.** t
23830 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 o [sqlite3_trace
23840 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 5d 20 69 73 _v2(D,M,X,P)] is
23850 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e an OR-ed combin
23860 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 ation of one or
23870 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 more of.** the f
23880 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e ollowing constan
23890 74 73 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 ts. ^The first
238a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
238b0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a trace callback.*
238c0 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 * is one of the
238d0 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 following consta
238e0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 nts..**.** New t
238f0 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 racing constants
23900 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
23910 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
23920 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 ..**.** ^A trace
23930 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f callback has fo
23940 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 ur arguments: xC
23950 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 allback(T,C,P,X)
23960 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 ..** ^The T argu
23970 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 ment is one of t
23980 68 65 20 69 6e 74 65 67 65 72 20 74 79 70 65 20 he integer type
23990 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 codes above..**
239a0 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 ^The C argument
239b0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
239c0 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 context pointer
239d0 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 passed in as th
239e0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 e.** fourth argu
239f0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
23a00 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a _trace_v2()]..**
23a10 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 The P and X arg
23a20 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 uments are point
23a30 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e ers whose meanin
23a40 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a gs depend on T..
23a50 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b **.** <dl>.** [[
23a60 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d SQLITE_TRACE_STM
23a70 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 T]] <dt>SQLITE_T
23a80 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a RACE_STMT</dt>.*
23a90 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 * <dd>^An SQLITE
23aa0 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c _TRACE_STMT call
23ab0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
23ac0 77 68 65 6e 20 61 20 70 72 65 70 61 72 65 64 20 when a prepared
23ad0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 statement.** fir
23ae0 73 74 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e st begins runnin
23af0 67 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 g and possibly a
23b00 74 20 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75 t other times du
23b10 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 ring the.** exec
23b20 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 ution of the pre
23b30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c pared statement,
23b40 20 73 75 63 68 20 61 73 20 61 74 20 74 68 65 20 such as at the
23b50 73 74 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a start of each.**
23b60 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 trigger subprog
23b70 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75 ram. ^The P argu
23b80 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
23b90 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 r to the.** [pre
23ba0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
23bb0 2e 20 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e . ^The X argumen
23bc0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
23bd0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 o a string which
23be0 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70 .** is the unexp
23bf0 61 6e 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f anded SQL text o
23c00 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 f the prepared s
23c10 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 tatement or an S
23c20 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 QL comment .** t
23c30 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 hat indicates th
23c40 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 e invocation of
23c50 61 20 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65 a trigger. ^The
23c60 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f callback can co
23c70 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d mpute.** the sam
23c80 65 20 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c e text that woul
23c90 64 20 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 d have been retu
23ca0 72 6e 65 64 20 62 79 20 74 68 65 20 6c 65 67 61 rned by the lega
23cb0 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 cy [sqlite3_trac
23cc0 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 e()].** interfac
23cd0 65 20 62 79 20 75 73 69 6e 67 20 74 68 65 20 58 e by using the X
23ce0 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 argument when X
23cf0 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d begins with "--
23d00 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a " and invoking.*
23d10 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e * [sqlite3_expan
23d20 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 ded_sql(P)] othe
23d30 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 rwise..**.** [[S
23d40 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 QLITE_TRACE_PROF
23d50 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 ILE]] <dt>SQLITE
23d60 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f _TRACE_PROFILE</
23d70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 dt>.** <dd>^An S
23d80 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 QLITE_TRACE_PROF
23d90 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f ILE callback pro
23da0 76 69 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74 vides approximat
23db0 65 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 ely the same.**
23dc0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 information as i
23dd0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 s provided by th
23de0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 e [sqlite3_profi
23df0 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a le()] callback..
23e00 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 ** ^The P argume
23e10 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 nt is a pointer
23e20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 to the [prepared
23e30 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 statement] and
23e40 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e the.** X argumen
23e50 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 t points to a 64
23e60 2d 62 69 74 20 69 6e 74 65 67 65 72 20 77 68 69 -bit integer whi
23e70 63 68 20 69 73 20 74 68 65 20 65 73 74 69 6d 61 ch is the estima
23e80 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 ted of.** the nu
23e90 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f mber of nanoseco
23ea0 6e 64 20 74 68 61 74 20 74 68 65 20 70 72 65 70 nd that the prep
23eb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 ared statement t
23ec0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e ook to run..** ^
23ed0 54 68 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 The SQLITE_TRACE
23ee0 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 _PROFILE callbac
23ef0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 k is invoked whe
23f00 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 n the statement
23f10 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 finishes..**.**
23f20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 [[SQLITE_TRACE_R
23f30 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f OW]] <dt>SQLITE_
23f40 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a TRACE_ROW</dt>.*
23f50 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 * <dd>^An SQLITE
23f60 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 _TRACE_ROW callb
23f70 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
23f80 68 65 6e 65 76 65 72 20 61 20 70 72 65 70 61 72 henever a prepar
23f90 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 ed.** statement
23fa0 67 65 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67 generates a sing
23fb0 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 le row of result
23fc0 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 . .** ^The P ar
23fd0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
23fe0 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 ter to the [prep
23ff0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
24000 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 and the.** X arg
24010 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e ument is unused.
24020 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
24030 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 TRACE_CLOSE]] <d
24040 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 t>SQLITE_TRACE_C
24050 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LOSE</dt>.** <dd
24060 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 >^An SQLITE_TRAC
24070 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b E_CLOSE callback
24080 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e is invoked when
24090 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 a database.** c
240a0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 onnection closes
240b0 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 ..** ^The P argu
240c0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
240d0 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 r to the [databa
240e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f se connection] o
240f0 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 bject.** and the
24100 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 X argument is u
24110 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a nused..** </dl>.
24120 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
24130 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20 E_TRACE_STMT
24140 20 20 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 0x01.#define
24150 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f SQLITE_TRACE_PRO
24160 46 49 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65 FILE 0x02.#de
24170 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 fine SQLITE_TRAC
24180 45 5f 52 4f 57 20 20 20 20 20 20 20 20 30 78 30 E_ROW 0x0
24190 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
241a0 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 _TRACE_CLOSE
241b0 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 0x08../*.** CA
241c0 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 PI3REF: SQL Trac
241d0 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 e Hook.** METHOD
241e0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
241f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 ^The sqlite3_tra
24200 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 ce_v2(D,M,X,P) i
24210 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
24220 72 73 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62 rs a trace callb
24230 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ack.** function
24240 58 20 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62 X against [datab
24250 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
24260 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74 D, using propert
24270 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 y mask M.** and
24280 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 context pointer
24290 50 2e 20 20 5e 49 66 20 74 68 65 20 58 20 63 61 P. ^If the X ca
242a0 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c llback is.** NUL
242b0 4c 20 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61 L or if the M ma
242c0 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e sk is zero, then
242d0 20 74 72 61 63 69 6e 67 20 69 73 20 64 69 73 61 tracing is disa
242e0 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 bled. The.** M
242f0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
24300 62 65 20 74 68 65 20 62 69 74 77 69 73 65 20 4f be the bitwise O
24310 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e R-ed combination
24320 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d of.** zero or m
24330 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 ore [SQLITE_TRAC
24340 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a E] constants..**
24350 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 .** ^Each call t
24360 6f 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 o either sqlite3
24370 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 _trace() or sqli
24380 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f te3_trace_v2() o
24390 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 verrides .** (ca
243a0 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 ncels) any prior
243b0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
243c0 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 3_trace() or sql
243d0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e ite3_trace_v2().
243e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 .**.** ^The X ca
243f0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
24400 64 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f d whenever any o
24410 66 20 74 68 65 20 65 76 65 6e 74 73 20 69 64 65 f the events ide
24420 6e 74 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d ntified by .** m
24430 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 ask M occur. ^T
24440 68 65 20 69 6e 74 65 67 65 72 20 72 65 74 75 72 he integer retur
24450 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 n value from the
24460 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 callback is cur
24470 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 rently.** ignore
24480 64 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d d, though this m
24490 61 79 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 ay change in fut
244a0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43 ure releases. C
244b0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 allback.** imple
244c0 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c mentations shoul
244d0 64 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f d return zero to
244e0 20 65 6e 73 75 72 65 20 66 75 74 75 72 65 20 63 ensure future c
244f0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a ompatibility..**
24500 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c .** ^A trace cal
24510 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
24520 20 77 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d with four argum
24530 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 ents: callback(T
24540 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 ,C,P,X)..** ^The
24550 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f T argument is o
24560 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 ne of the [SQLIT
24570 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 E_TRACE].** cons
24580 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74 tants to indicat
24590 65 20 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61 e why the callba
245a0 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a ck was invoked..
245b0 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 ** ^The C argume
245c0 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 nt is a copy of
245d0 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e the context poin
245e0 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e ter..** The P an
245f0 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 d X arguments ar
24600 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 e pointers whose
24610 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 meanings depend
24620 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 on T..**.** The
24630 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 sqlite3_trace_v
24640 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 2() interface is
24650 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70 intended to rep
24660 6c 61 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a lace the legacy.
24670 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 ** interfaces [s
24680 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 qlite3_trace()]
24690 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f and [sqlite3_pro
246a0 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 file()], both of
246b0 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 which.** are de
246c0 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 precated..*/.int
246d0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 sqlite3_trace_v
246e0 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 2(. sqlite3*,.
246f0 20 75 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c unsigned uMask,
24700 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 . int(*xCallbac
24710 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 k)(unsigned,void
24720 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a *,void*,void*),.
24730 20 20 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a void *pCtx.);.
24740 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
24750 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 Query Progress
24760 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 Callbacks.** MET
24770 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
24780 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
24790 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 progress_handler
247a0 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 (D,N,X,P) interf
247b0 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 ace causes the c
247c0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 allback.** funct
247d0 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f ion X to be invo
247e0 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 ked periodically
247f0 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e during long run
24800 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a ning calls to.**
24810 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
24820 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ], [sqlite3_step
24830 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
24840 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f _get_table()] fo
24850 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f r.** database co
24860 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 nnection D. An
24870 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 example use for
24880 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 this.** interfac
24890 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 e is to keep a G
248a0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e UI updated durin
248b0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e g a large query.
248c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 .**.** ^The para
248d0 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 meter P is passe
248e0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 d through as the
248f0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 only parameter
24900 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 to the .** callb
24910 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 ack function X.
24920 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 ^The parameter
24930 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 N is the approxi
24940 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a mate number of .
24950 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 ** [virtual mach
24960 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 ine instructions
24970 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 ] that are evalu
24980 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 ated between suc
24990 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 cessive.** invoc
249a0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 ations of the ca
249b0 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e llback X. ^If N
249c0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e is less than on
249d0 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 e then the progr
249e0 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 ess.** handler i
249f0 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a s disabled..**.*
24a00 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 * ^Only a single
24a10 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
24a20 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 r may be defined
24a30 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 at one time per
24a40 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
24a50 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 nnection]; setti
24a60 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 ng a new progres
24a70 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c s handler cancel
24a80 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 s the.** old one
24a90 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 . ^Setting para
24aa0 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 meter X to NULL
24ab0 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f disables the pro
24ac0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a gress handler..*
24ad0 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 * ^The progress
24ae0 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 handler is also
24af0 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 disabled by sett
24b00 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 ing N to a value
24b10 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e less.** than 1.
24b20 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 .**.** ^If the p
24b30 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b rogress callback
24b40 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
24b50 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e o, the operation
24b60 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 is.** interrupt
24b70 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 ed. This featur
24b80 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
24b90 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 implement a.**
24ba0 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 "Cancel" button
24bb0 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 on a GUI progres
24bc0 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a s dialog box..**
24bd0 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 .** The progress
24be0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 handler callbac
24bf0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e k must not do an
24c00 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
24c10 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
24c20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
24c30 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
24c40 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e the progress han
24c50 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 dler..** Note th
24c60 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
24c70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
24c80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
24c90 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
24ca0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
24cb0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
24cc0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
24cd0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
24ce0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f agraph..**.*/.vo
24cf0 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 id sqlite3_progr
24d00 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 ess_handler(sqli
24d10 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a te3*, int, int(*
24d20 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 )(void*), void*)
24d30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
24d40 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 F: Opening A New
24d50 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
24d60 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 tion.** CONSTRUC
24d70 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a TOR: sqlite3.**.
24d80 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
24d90 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 es open an SQLit
24da0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
24db0 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 as specified by
24dc0 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 the .** filename
24dd0 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 argument. ^The
24de0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
24df0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 t is interpreted
24e00 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a as UTF-8 for.**
24e10 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
24e20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e and sqlite3_open
24e30 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 _v2() and as UTF
24e40 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 -16 in the nativ
24e50 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 e byte.** order
24e60 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e for sqlite3_open
24e70 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 16(). ^(A [datab
24e80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
24e90 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c handle is usuall
24ea0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e y.** returned in
24eb0 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 *ppDb, even if
24ec0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e an error occurs.
24ed0 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 The only excep
24ee0 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 tion is that.**
24ef0 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 if SQLite is una
24f00 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 ble to allocate
24f10 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 memory to hold t
24f20 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
24f30 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 ect,.** a NULL w
24f40 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 ill be written i
24f50 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 nto *ppDb instea
24f60 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 d of a pointer t
24f70 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a o the [sqlite3].
24f80 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 ** object.)^ ^(I
24f90 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 f the database i
24fa0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 s opened (and/or
24fb0 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 created) succes
24fc0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 sfully, then.**
24fd0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 [SQLITE_OK] is r
24fe0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 eturned. Otherw
24ff0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f ise an [error co
25000 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
25010 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 )^ ^The.** [sqli
25020 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 te3_errmsg()] or
25030 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
25040 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 16()] routines c
25050 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 an be used to ob
25060 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 tain.** an Engli
25070 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 sh language desc
25080 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 ription of the e
25090 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 rror following a
250a0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a failure of any.
250b0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ** of the sqlite
250c0 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 3_open() routine
250d0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 s..**.** ^The de
250e0 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 fault encoding w
250f0 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 ill be UTF-8 for
25100 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74 databases creat
25110 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 ed using.** sqli
25120 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 te3_open() or sq
25130 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
25140 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 ^The default e
25150 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 ncoding for data
25160 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 bases.** created
25170 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f using sqlite3_o
25180 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 pen16() will be
25190 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 UTF-16 in the na
251a0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e tive byte order.
251b0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f .**.** Whether o
251c0 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f r not an error o
251d0 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 ccurs when it is
251e0 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 opened, resourc
251f0 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 es.** associated
25200 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 with the [datab
25210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
25220 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 handle should be
25230 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 released by.**
25240 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 passing it to [s
25250 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 qlite3_close()]
25260 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f when it is no lo
25270 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a nger required..*
25280 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
25290 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 _open_v2() inter
252a0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 face works like
252b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a sqlite3_open().*
252c0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 * except that it
252d0 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 accepts two add
252e0 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 itional paramete
252f0 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 rs for additiona
25300 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 l control.** ove
25310 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 r the new databa
25320 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 se connection.
25330 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 ^(The flags para
25340 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 meter to.** sqli
25350 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 te3_open_v2() ca
25360 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a n take one of.**
25370 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 the following t
25380 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 hree values, opt
25390 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 ionally combined
253a0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 with the .** [S
253b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
253c0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 EX], [SQLITE_OPE
253d0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 N_FULLMUTEX], [S
253e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
253f0 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c DCACHE],.** [SQL
25400 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
25410 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b CACHE], and/or [
25420 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d SQLITE_OPEN_URI]
25430 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 flags:)^.**.**
25440 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 <dl>.** ^(<dt>[S
25450 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
25460 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NLY]</dt>.** <dd
25470 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 >The database is
25480 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d opened in read-
25490 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 only mode. If t
254a0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 he database does
254b0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 not.** already
254c0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 exist, an error
254d0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 is returned.</dd
254e0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e >)^.**.** ^(<dt>
254f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
25500 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 DWRITE]</dt>.**
25510 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 <dd>The database
25520 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
25530 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 eading and writi
25540 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 ng if possible,
25550 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e or reading.** on
25560 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 ly if the file i
25570 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 s write protecte
25580 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 d by the operati
25590 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 ng system. In e
255a0 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 ither.** case th
255b0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 e database must
255c0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f already exist, o
255d0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f therwise an erro
255e0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f r is returned.</
255f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 dd>)^.**.** ^(<d
25600 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 t>[SQLITE_OPEN_R
25610 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c EADWRITE] | [SQL
25620 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d ITE_OPEN_CREATE]
25630 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
25640 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
25650 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 ned for reading
25660 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 and writing, and
25670 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a is created if.*
25680 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c * it does not al
25690 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 ready exist. Thi
256a0 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f s is the behavio
256b0 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 r that is always
256c0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c used for.** sql
256d0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
256e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
256f0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c .</dd>)^.** </dl
25700 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 >.**.** If the 3
25710 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
25720 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
25730 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 ) is not one of
25740 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 the.** combinati
25750 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 ons shown above
25760 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 optionally combi
25770 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a ned with other.*
25780 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 * [SQLITE_OPEN_R
25790 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 EADONLY | SQLITE
257a0 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a _OPEN_* bits].**
257b0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
257c0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e or is undefined.
257d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b .**.** ^If the [
257e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
257f0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 TEX] flag is set
25800 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 , then the datab
25810 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
25820 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d * opens in the m
25830 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 ulti-thread [thr
25840 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 eading mode] as
25850 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 long as the sing
25860 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 le-thread.** mod
25870 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 e has not been s
25880 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 et at compile-ti
25890 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 me or start-time
258a0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 . ^If the.** [S
258b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
258c0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 UTEX] flag is se
258d0 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 t then the datab
258e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f ase connection o
258f0 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 pens.** in the s
25900 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 erialized [threa
25910 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 ding mode] unles
25920 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 s single-thread
25930 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c was.** previousl
25940 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f y selected at co
25950 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 mpile-time or st
25960 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 art-time..** ^Th
25970 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 e [SQLITE_OPEN_S
25980 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 HAREDCACHE] flag
25990 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 causes the data
259a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
259b0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c to be.** eligibl
259c0 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 e to use [shared
259d0 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 cache mode], re
259e0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
259f0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 her or not share
25a00 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e d.** cache is en
25a10 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c abled using [sql
25a20 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 ite3_enable_shar
25a30 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 ed_cache()]. ^T
25a40 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 he.** [SQLITE_OP
25a50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d EN_PRIVATECACHE]
25a60 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 flag causes the
25a70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
25a80 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 tion to not.** p
25a90 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 articipate in [s
25aa0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 hared cache mode
25ab0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 ] even if it is
25ac0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e enabled..**.** ^
25ad0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
25ae0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
25af0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 open_v2() is the
25b00 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 name of the.**
25b10 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
25b20 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 ject that define
25b30 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 s the operating
25b40 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 system interface
25b50 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 that.** the new
25b60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
25b70 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e tion should use.
25b80 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 ^If the fourth
25b90 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a parameter is.**
25ba0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
25bb0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 then the default
25bc0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
25bd0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a bject is used..*
25be0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c *.** ^If the fil
25bf0 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 ename is ":memor
25c00 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 y:", then a priv
25c10 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 ate, temporary i
25c20 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 n-memory databas
25c30 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 e.** is created
25c40 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 for the connecti
25c50 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 on. ^This in-me
25c60 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 mory database wi
25c70 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a ll vanish when.*
25c80 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
25c90 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f onnection is clo
25ca0 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 sed. Future ver
25cb0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
25cc0 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 might.** make us
25cd0 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 e of additional
25ce0 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 special filename
25cf0 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 s that begin wit
25d00 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 h the ":" charac
25d10 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 ter..** It is re
25d20 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 commended that w
25d30 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 hen a database f
25d40 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 ilename actually
25d50 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 does begin with
25d60 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 .** a ":" charac
25d70 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 ter you should p
25d80 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 refix the filena
25d90 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 me with a pathna
25da0 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e me such as.** ".
25db0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 /" to avoid ambi
25dc0 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 guity..**.** ^If
25dd0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 the filename is
25de0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
25df0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 , then a private
25e00 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f , temporary.** o
25e10 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 n-disk database
25e20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e will be created.
25e30 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 ^This private
25e40 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
25e50 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
25e60 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f y deleted as soo
25e70 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 n as the databas
25e80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
25e90 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b closed..**.** [[
25ea0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e URI filenames in
25eb0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d sqlite3_open()]
25ec0 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 ] <h3>URI Filena
25ed0 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e mes</h3>.**.** ^
25ee0 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 If [URI filename
25ef0 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e ] interpretation
25f00 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 is enabled, and
25f10 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 the filename ar
25f20 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 gument.** begins
25f30 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 with "file:", t
25f40 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 hen the filename
25f50 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
25f60 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a as a URI. ^URI.*
25f70 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 * filename inter
25f80 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 pretation is ena
25f90 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c bled if the [SQL
25fa0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c ITE_OPEN_URI] fl
25fb0 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 ag is.** set in
25fc0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 the third argume
25fd0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 nt to sqlite3_op
25fe0 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 en_v2(), or if i
25ff0 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e t has.** been en
26000 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 abled globally u
26010 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 sing the [SQLITE
26020 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 _CONFIG_URI] opt
26030 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 ion with the.**
26040 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
26050 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 )] method or by
26060 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f the [SQLITE_USE_
26070 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d URI] compile-tim
26080 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49 e option..** URI
26090 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 filename interp
260a0 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e retation is turn
260b0 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 ed off.** by def
260c0 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 ault, but future
260d0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
260e0 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 ite might enable
260f0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a URI filename.**
26100 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 interpretation
26110 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 by default. See
26120 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 "[URI filenames
26130 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 ]" for additiona
26140 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e l.** information
26150 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 ..**.** URI file
26160 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 names are parsed
26170 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 according to RF
26180 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 C 3986. ^If the
26190 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a URI contains an.
261a0 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 ** authority, th
261b0 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 en it must be ei
261c0 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 ther an empty st
261d0 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 ring or the stri
261e0 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 ng .** "localhos
261f0 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 t". ^If the auth
26200 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 ority is not an
26210 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 empty string or
26220 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 "localhost", an
26230 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 .** error is ret
26240 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c urned to the cal
26250 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 ler. ^The fragme
26260 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 nt component of
26270 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 a URI, if .** pr
26280 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 esent, is ignore
26290 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 d..**.** ^SQLite
262a0 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 uses the path c
262b0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 omponent of the
262c0 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 URI as the name
262d0 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 of the disk file
262e0 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 .** which contai
262f0 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e ns the database.
26300 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 ^If the path be
26310 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 gins with a '/'
26320 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 character, .** t
26330 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 hen it is interp
26340 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f reted as an abso
26350 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 lute path. ^If t
26360 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 he path does not
26370 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 begin .** with
26380 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 a '/' (meaning t
26390 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 hat the authorit
263a0 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 y section is omi
263b0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 tted from the UR
263c0 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 I).** then the p
263d0 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 ath is interpret
263e0 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 ed as a relative
263f0 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 path. .** ^(On
26400 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 windows, the fir
26410 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 st component of
26420 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 an absolute path
26430 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 .** is a drive
26440 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 specification (e
26450 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a .g. "C:").)^.**.
26460 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 ** [[core URI qu
26470 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d ery parameters]]
26480 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f .** The query co
26490 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 mponent of a URI
264a0 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 may contain par
264b0 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 ameters that are
264c0 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 interpreted.**
264d0 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 either by SQLite
264e0 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 itself, or by a
264f0 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 [VFS | custom V
26500 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
26510 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e n]..** SQLite an
26520 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b d its built-in [
26530 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 VFSes] interpret
26540 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e the.** followin
26550 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 g query paramete
26560 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a rs:.**.** <ul>.*
26570 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c * <li> <b>vfs<
26580 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 /b>: ^The "vfs"
26590 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
265a0 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 used to specify
265b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 the name of.**
265c0 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 a VFS object
265d0 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 that provides t
265e0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
265f0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 tem interface th
26600 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 at should.**
26610 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 be used to acce
26620 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ss the database
26630 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 file on disk. ^I
26640 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 f this option is
26650 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 set to.** a
26660 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 n empty string t
26670 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f he default VFS o
26680 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e bject is used. ^
26690 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e Specifying an un
266a0 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 known.** VFS
266b0 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 is an error. ^I
266c0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 f sqlite3_open_v
266d0 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 2() is used and
266e0 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 the vfs option i
266f0 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 s.** present
26700 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 , then the VFS s
26710 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
26720 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 option takes pre
26730 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 cedence over.**
26740 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 the value pa
26750 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 ssed as the four
26760 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
26770 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
26780 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 )..**.** <li>
26790 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 <b>mode</b>: ^(T
267a0 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 he mode paramete
267b0 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 r may be set to
267c0 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 either "ro", "rw
267d0 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c ",.** "rwc",
267e0 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 or "memory". At
267f0 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 tempting to set
26800 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 it to any other
26810 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 value is.**
26820 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 an error)^. .**
26830 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 ^If "ro" is
26840 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 specified, then
26850 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
26860 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d opened for read-
26870 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 only .** acc
26880 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 ess, just as if
26890 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e the [SQLITE_OPEN
268a0 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 _READONLY] flag
268b0 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 had been set in
268c0 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 the .** thir
268d0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 d argument to sq
268e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
268f0 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 ^If the mode op
26900 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a tion is set to .
26910 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 ** "rw", the
26920 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 n the database i
26930 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
26940 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 d-write (but not
26950 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 create) .**
26960 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 access, as if S
26970 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
26980 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 RITE (but not SQ
26990 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
269a0 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 ) had .** be
269b0 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 en set. ^Value "
269c0 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 rwc" is equivale
269d0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f nt to setting bo
269e0 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 th .** SQLIT
269f0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
26a00 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e and SQLITE_OPEN
26a10 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 _CREATE. ^If th
26a20 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 e mode option is
26a30 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 .** set to "
26a40 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 memory" then a p
26a50 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 ure [in-memory d
26a60 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 atabase] that ne
26a70 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 ver reads.**
26a80 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 or writes from
26a90 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 disk is used. ^I
26aa0 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f t is an error to
26ab0 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 specify a value
26ac0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 for.** the
26ad0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 mode parameter t
26ae0 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 hat is less rest
26af0 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 rictive than tha
26b00 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a t specified by.*
26b10 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 * the flags
26b20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 passed in the th
26b30 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
26b40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
26b50 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e ()..**.** <li>
26b60 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e <b>cache</b>: ^
26b70 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 The cache parame
26b80 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 ter may be set t
26b90 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64 o either "shared
26ba0 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 " or.** "pri
26bb0 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 vate". ^Setting
26bc0 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 it to "shared" i
26bd0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 s equivalent to
26be0 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 setting the.**
26bf0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 SQLITE_OPEN_S
26c00 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69 HAREDCACHE bit i
26c10 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 n the flags argu
26c20 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a ment passed to.*
26c30 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 * sqlite3_op
26c40 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e en_v2(). ^Settin
26c50 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 g the cache para
26c60 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 meter to "privat
26c70 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 e" is .** eq
26c80 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 uivalent to sett
26c90 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f ing the SQLITE_O
26ca0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 PEN_PRIVATECACHE
26cb0 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 bit..** ^If
26cc0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
26cd0 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 () is used and t
26ce0 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d he "cache" param
26cf0 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 eter is present
26d00 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 in.** a URI
26d10 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 filename, its va
26d20 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e lue overrides an
26d30 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 y behavior reque
26d40 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a sted by setting.
26d50 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 ** SQLITE_OP
26d60 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 EN_PRIVATECACHE
26d70 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 or SQLITE_OPEN_S
26d80 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e HAREDCACHE flag.
26d90 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e .**.** <li> <b>
26da0 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 psow</b>: ^The p
26db0 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e sow parameter in
26dc0 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20 dicates whether
26dd0 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 or not the.**
26de0 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 [powersafe ove
26df0 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 rwrite] property
26e00 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f does or does no
26e10 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a t apply to the.*
26e20 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 * storage me
26e30 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 dia on which the
26e40 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 database file r
26e50 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c esides..**.** <
26e60 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 li> <b>nolock</b
26e70 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 >: ^The nolock p
26e80 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f arameter is a bo
26e90 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 olean query para
26ea0 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 meter.** whi
26eb0 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c ch if set disabl
26ec0 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 es file locking
26ed0 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 in rollback jour
26ee0 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 nal modes. This
26ef0 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 .** is usefu
26f00 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 l for accessing
26f10 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 a database on a
26f20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 filesystem that
26f30 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 does not.**
26f40 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e support locking.
26f50 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 Caution: Data
26f60 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 base corruption
26f70 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 might result if
26f80 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f two.** or mo
26f90 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 re processes wri
26fa0 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 te to the same d
26fb0 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 atabase and any
26fc0 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 one of those.**
26fd0 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 processes us
26fe0 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a es nolock=1..**.
26ff0 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 ** <li> <b>immu
27000 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 table</b>: ^The
27010 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 immutable parame
27020 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e ter is a boolean
27030 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 query.** pa
27040 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 rameter that ind
27050 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 icates that the
27060 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 database file is
27070 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 stored on.**
27080 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 read-only medi
27090 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 a. ^When immuta
270a0 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 ble is set, SQLi
270b0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 te assumes that
270c0 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 the.** datab
270d0 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 ase file cannot
270e0 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e be changed, even
270f0 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 by a process wi
27100 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 th higher.**
27110 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 privilege, and
27120 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 so the database
27130 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f is opened read-o
27140 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b nly and all lock
27150 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 ing.** and c
27160 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 hange detection
27170 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 is disabled. Ca
27180 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 ution: Setting t
27190 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 he immutable.**
271a0 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 property on
271b0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 a database file
271c0 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 that does in fac
271d0 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 t change can res
271e0 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e ult.** in in
271f0 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65 correct query re
27200 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 sults and/or [SQ
27210 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 LITE_CORRUPT] er
27220 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 rors..** See
27230 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 also: [SQLITE_I
27240 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e OCAP_IMMUTABLE].
27250 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f .** .** </
27260 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 ul>.**.** ^Speci
27270 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e fying an unknown
27280 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 parameter in th
27290 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e e query componen
272a0 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f t of a URI is no
272b0 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 t an.** error.
272c0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 Future versions
272d0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 of SQLite might
272e0 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 understand addit
272f0 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 ional query.** p
27300 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 arameters. See
27310 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 "[query paramete
27320 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 rs with special
27330 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 meaning to SQLit
27340 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 e]" for.** addit
27350 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
27360 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 n..**.** [[URI f
27370 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 ilename examples
27380 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e ]] <h3>URI filen
27390 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 ame examples</h3
273a0 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 >.**.** <table b
273b0 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d order="1" align=
273c0 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 center cellpaddi
273d0 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 ng=5>.** <tr><th
273e0 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 > URI filenames
273f0 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 <th> Results.**
27400 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 <tr><td> file:da
27410 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 ta.db <td> .**
27420 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 Open the
27430 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 file "data.db"
27440 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 in the current d
27450 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 irectory..** <tr
27460 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 ><td> file:/home
27470 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 /fred/data.db<br
27480 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 >.** fi
27490 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f le:///home/fred/
274a0 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a data.db <br> .**
274b0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f file:/
274c0 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f /localhost/home/
274d0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 fred/data.db <br
274e0 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 > <td> .**
274f0 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 Open the dat
27500 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d abase file "/hom
27510 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e e/fred/data.db".
27520 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c .** <tr><td> fil
27530 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d e://darkstar/hom
27540 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c e/fred/data.db <
27550 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 td> .**
27560 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b An error. "dark
27570 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 star" is not a r
27580 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 ecognized author
27590 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 ity..** <tr><td
275a0 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 style="white-spa
275b0 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 ce:nowrap"> .**
275c0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f file://
275d0 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 /C:/Documents%20
275e0 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 and%20Settings/f
275f0 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 red/Desktop/data
27600 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 .db.** <td>
27610 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 Windows only: Op
27620 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 en the file "dat
27630 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 a.db" on fred's
27640 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 desktop on drive
27650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e .** C:.
27660 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 Note that the %
27670 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 20 escaping in t
27680 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e his example is n
27690 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 ot strictly .**
276a0 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 necessa
276b0 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 ry - space chara
276c0 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 cters can be use
276d0 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 d literally.**
276e0 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 in URI f
276f0 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 ilenames..** <tr
27700 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e ><td> file:data.
27710 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 db?mode=ro&cache
27720 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a =private <td> .*
27730 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 * Open
27740 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 file "data.db" i
27750 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 n the current di
27760 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 rectory for read
27770 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a -only access..**
27780 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 Regard
27790 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
277a0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 or not shared-ca
277b0 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 che mode is enab
277c0 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 led by.**
277d0 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 default, use
277e0 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e a private cache.
277f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c .** <tr><td> fil
27800 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 e:/home/fred/dat
27810 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f a.db?vfs=unix-do
27820 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 tfile <td>.**
27830 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 Open file
27840 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 "/home/fred/dat
27850 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 a.db". Use the s
27860 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 pecial VFS "unix
27870 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 -dotfile".**
27880 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20 that uses
27890 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 dot-files in pla
278a0 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 ce of posix advi
278b0 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a sory locking..**
278c0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 <tr><td> file:d
278d0 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 ata.db?mode=read
278e0 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 only <td> .**
278f0 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e An error.
27900 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e "readonly" is n
27910 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f ot a valid optio
27920 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 n for the "mode"
27930 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c parameter..** <
27940 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 /table>.**.** ^U
27950 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 RI hexadecimal e
27960 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 scape sequences
27970 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 (%HH) are suppor
27980 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 ted within the p
27990 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 ath and.** query
279a0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 components of a
279b0 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 URI. A hexadeci
279c0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 mal escape seque
279d0 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 nce consists of
279e0 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 a.** percent sig
279f0 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 n - "%" - follow
27a00 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 ed by exactly tw
27a10 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 o hexadecimal di
27a20 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 gits .** specify
27a30 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c ing an octet val
27a40 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 ue. ^Before the
27a50 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f path or query co
27a60 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a mponents of a.**
27a70 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 URI filename ar
27a80 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 e interpreted, t
27a90 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 hey are encoded
27aa0 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 using UTF-8 and
27ab0 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 all .** hexadeci
27ac0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 mal escape seque
27ad0 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 nces replaced by
27ae0 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 a single byte c
27af0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a ontaining the.**
27b00 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f corresponding o
27b10 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 ctet. If this pr
27b20 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 ocess generates
27b30 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 an invalid UTF-8
27b40 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 encoding,.** th
27b50 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
27b60 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c defined..**.** <
27b70 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 b>Note to Window
27b80 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 s users:</b> Th
27b90 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 e encoding used
27ba0 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 for the filename
27bb0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 argument.** of
27bc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 sqlite3_open() a
27bd0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f nd sqlite3_open_
27be0 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 v2() must be UTF
27bf0 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 -8, not whatever
27c00 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 .** codepage is
27c10 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 currently define
27c20 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f d. Filenames co
27c30 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 ntaining interna
27c40 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 tional.** charac
27c50 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e ters must be con
27c60 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 verted to UTF-8
27c70 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 prior to passing
27c80 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 them into.** sq
27c90 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 lite3_open() or
27ca0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
27cb0 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 )..**.** <b>Note
27cc0 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 to Windows Runt
27cd0 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 ime users:</b>
27ce0 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 The temporary di
27cf0 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 rectory must be
27d00 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 set.** prior to
27d10 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f calling sqlite3_
27d20 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 open() or sqlite
27d30 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 3_open_v2(). Ot
27d40 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 herwise, various
27d50 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 .** features tha
27d60 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 t require the us
27d70 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 e of temporary f
27d80 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a iles may fail..*
27d90 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
27da0 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 sqlite3_temp_dir
27db0 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 ectory].*/.int s
27dc0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 qlite3_open(. c
27dd0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e onst char *filen
27de0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
27df0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
27e00 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 -8) */. sqlite3
27e10 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 **ppDb
27e20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
27e30 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a db handle */.);.
27e40 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e int sqlite3_open
27e50 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 16(. const void
27e60 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a *filename, /*
27e70 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 Database filena
27e80 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 me (UTF-16) */.
27e90 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 sqlite3 **ppDb
27ea0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
27eb0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
27ec0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 e */.);.int sqli
27ed0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 te3_open_v2(. c
27ee0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e onst char *filen
27ef0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
27f00 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
27f10 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 -8) */. sqlite3
27f20 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 **ppDb,
27f30 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
27f40 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 db handle */. i
27f50 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 nt flags,
27f60 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 /* Flags
27f70 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
27f80 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 *zVfs /*
27f90 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 Name of VFS modu
27fa0 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a le to use */.);.
27fb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
27fc0 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 Obtain Values F
27fd0 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 or URI Parameter
27fe0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 s.**.** These ar
27ff0 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e e utility routin
28000 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 es, useful to VF
28010 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
28020 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a s, that check.**
28030 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 to see if a dat
28040 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 abase file was a
28050 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 URI that contai
28060 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 ned a specific q
28070 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 uery .** paramet
28080 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 er, and if so ob
28090 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 tains the value
280a0 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 of that query pa
280b0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 rameter..**.** I
280c0 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 f F is the datab
280d0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 ase filename poi
280e0 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f nter passed into
280f0 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 the xOpen() met
28100 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 hod of .** a VFS
28110 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
28120 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 when the flags p
28130 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 arameter to xOpe
28140 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a n() has one or .
28150 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b ** more of the [
28160 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d SQLITE_OPEN_URI]
28170 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e or [SQLITE_OPEN
28180 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 _MAIN_DB] bits s
28190 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 et and.** P is t
281a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 he name of the q
281b0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 uery parameter,
281c0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f then.** sqlite3_
281d0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c uri_parameter(F,
281e0 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 P) returns the v
281f0 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a alue of the P.**
28200 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 parameter if it
28210 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c exists or a NUL
28220 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 L pointer if P d
28230 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 oes not appear a
28240 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 s a .** query pa
28250 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 rameter on F. I
28260 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 f P is a query p
28270 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a arameter of F.**
28280 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 has no explicit
28290 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c value, then sql
282a0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 ite3_uri_paramet
282b0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a er(F,P) returns.
282c0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
282d0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e an empty string.
282e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
282f0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
28300 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 ,P,B) routine as
28310 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 sumes that P is
28320 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 a boolean.** par
28330 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 ameter and retur
28340 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 ns true (1) or f
28350 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 alse (0) accordi
28360 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a ng to the value.
28370 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 ** of P. The sq
28380 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
28390 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 n(F,P,B) routine
283a0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 returns true (1
283b0 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 ) if the.** valu
283c0 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d e of query param
283d0 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 eter P is one of
283e0 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 "yes", "true",
283f0 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a or "on" in any.*
28400 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 * case or if the
28410 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 value begins wi
28420 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 th a non-zero nu
28430 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 mber. The .** s
28440 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 qlite3_uri_boole
28450 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e an(F,P,B) routin
28460 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 es returns false
28470 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 (0) if the valu
28480 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 e of.** query pa
28490 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 rameter P is one
284a0 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 of "no", "false
284b0 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 ", or "off" in a
284c0 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 ny case or.** if
284d0 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e the value begin
284e0 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 s with a numeric
284f0 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 zero. If P is
28500 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 not a query.** p
28510 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 arameter on F or
28520 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 if the value of
28530 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d P is does not m
28540 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a atch any of the.
28550 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 ** above, then s
28560 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 qlite3_uri_boole
28570 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e an(F,P,B) return
28580 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 s (B!=0)..**.**
28590 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f The sqlite3_uri_
285a0 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 int64(F,P,D) rou
285b0 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 tine converts th
285c0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 e value of P int
285d0 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 o a.** 64-bit si
285e0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 gned integer and
285f0 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e returns that in
28600 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 teger, or D if P
28610 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 does not.** exi
28620 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 st. If the valu
28630 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 e of P is someth
28640 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 ing other than a
28650 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a n integer, then.
28660 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 ** zero is retur
28670 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 ned..** .** If F
28680 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
28690 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 er, then sqlite3
286a0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 _uri_parameter(F
286b0 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c ,P) returns NULL
286c0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f and.** sqlite3_
286d0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
286e0 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 B) returns B. I
286f0 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c f F is not a NUL
28700 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a L pointer and.**
28710 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 is not a databa
28720 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 se file pathname
28730 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 pointer that SQ
28740 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f Lite passed into
28750 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 the xOpen.** VF
28760 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 S method, then t
28770 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 he behavior of t
28780 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 his routine is u
28790 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
287a0 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 bably.** undesir
287b0 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 able..*/.const c
287c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 har *sqlite3_uri
287d0 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 _parameter(const
287e0 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 char *zFilename
287f0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 , const char *zP
28800 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 aram);.int sqlit
28810 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 e3_uri_boolean(c
28820 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
28830 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 , const char *zP
28840 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 aram, int bDefau
28850 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 lt);.sqlite3_int
28860 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 64 sqlite3_uri_i
28870 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a nt64(const char*
28880 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 , const char*, s
28890 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a qlite3_int64);..
288a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
288b0 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 Error Codes And
288c0 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 Messages.** MET
288d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
288e0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 ** ^If the most
288f0 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a recent sqlite3_*
28900 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 API call associ
28910 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 ated with .** [d
28920 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
28930 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 on] D failed, th
28940 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 en the sqlite3_e
28950 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 rrcode(D) interf
28960 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 ace.** returns t
28970 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 he numeric [resu
28980 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 lt code] or [ext
28990 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
289a0 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 e] for that.** A
289b0 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 PI call..** If t
289c0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 he most recent A
289d0 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 PI call was succ
289e0 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 essful,.** then
289f0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
28a00 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 from sqlite3_er
28a10 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 rcode() is undef
28a20 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 ined..** ^The sq
28a30 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 lite3_extended_e
28a40 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 rrcode().** inte
28a50 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d rface is the sam
28a60 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 e except that it
28a70 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
28a80 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 the .** [extende
28a90 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 d result code] e
28aa0 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 ven when extende
28ab0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 d result codes a
28ac0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a re.** disabled..
28ad0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
28ae0 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 e3_errmsg() and
28af0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
28b00 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 () return Englis
28b10 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 h-language.** te
28b20 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 xt that describe
28b30 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 s the error, as
28b40 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
28b50 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 UTF-16 respectiv
28b60 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 ely..** ^(Memory
28b70 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 to hold the err
28b80 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e or message strin
28b90 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 g is managed int
28ba0 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 ernally..** The
28bb0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 application does
28bc0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 not need to wor
28bd0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 ry about freeing
28be0 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 the result..**
28bf0 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 However, the err
28c00 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 or string might
28c10 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f be overwritten o
28c20 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 r deallocated by
28c30 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 .** subsequent c
28c40 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 alls to other SQ
28c50 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 Lite interface f
28c60 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a unctions.)^.**.*
28c70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
28c80 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 rrstr() interfac
28c90 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e e returns the En
28ca0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 glish-language t
28cb0 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 ext.** that desc
28cc0 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c ribes the [resul
28cd0 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d t code], as UTF-
28ce0 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 8..** ^(Memory t
28cf0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 o hold the error
28d00 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
28d10 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 is managed inter
28d20 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 nally.** and mus
28d30 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 t not be freed b
28d40 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
28d50 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 n)^..**.** When
28d60 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b the serialized [
28d70 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
28d80 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 is in use, it mi
28d90 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 ght be the.** ca
28da0 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 se that a second
28db0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e error occurs on
28dc0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
28dd0 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a ad in between.**
28de0 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 the time of the
28df0 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 first error and
28e00 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 the call to the
28e10 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a se interfaces..*
28e20 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 * When that happ
28e30 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 ens, the second
28e40 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 error will be re
28e50 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 ported since the
28e60 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 se.** interfaces
28e70 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 always report t
28e80 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 he most recent r
28e90 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 esult. To avoid
28ea0 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 .** this, each t
28eb0 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e hread can obtain
28ec0 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f exclusive use o
28ed0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 f the [database
28ee0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a connection] D.**
28ef0 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 by invoking [sq
28f00 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 lite3_mutex_ente
28f10 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d r]([sqlite3_db_m
28f20 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 utex](D)) before
28f30 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f beginning.** to
28f40 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b use D and invok
28f50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
28f60 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 ex_leave]([sqlit
28f70 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 e3_db_mutex](D))
28f80 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 after.** all ca
28f90 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 lls to the inter
28fa0 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 faces listed her
28fb0 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e e are completed.
28fc0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 .**.** If an int
28fd0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 erface fails wit
28fe0 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c h SQLITE_MISUSE,
28ff0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 that means the
29000 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 interface.** was
29010 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 invoked incorre
29020 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c ctly by the appl
29030 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 ication. In tha
29040 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 t case, the.** e
29050 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 rror code and me
29060 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 ssage may or may
29070 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a not be set..*/.
29080 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 int sqlite3_errc
29090 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 ode(sqlite3 *db)
290a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 ;.int sqlite3_ex
290b0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 tended_errcode(s
290c0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e qlite3 *db);.con
290d0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
290e0 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a _errmsg(sqlite3*
290f0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
29100 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
29110 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 sqlite3*);.const
29120 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 char *sqlite3_e
29130 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a rrstr(int);../*.
29140 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 ** CAPI3REF: Pre
29150 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 pared Statement
29160 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 Object.** KEYWOR
29170 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 DS: {prepared st
29180 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 atement} {prepar
29190 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a ed statements}.*
291a0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
291b0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
291c0 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e represents a sin
291d0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e gle SQL statemen
291e0 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 t that.** has be
291f0 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f en compiled into
29200 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 binary form and
29210 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 is ready to be
29220 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a evaluated..**.**
29230 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 Think of each S
29240 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 QL statement as
29250 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 a separate compu
29260 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 ter program. Th
29270 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 e.** original SQ
29280 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 L text is source
29290 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 code. A prepar
292a0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a ed statement obj
292b0 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 ect .** is the c
292c0 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 ompiled object c
292d0 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 ode. All SQL mu
292e0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 st be converted
292f0 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 into a.** prepar
29300 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 ed statement bef
29310 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 ore it can be ru
29320 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 n..**.** The lif
29330 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 e-cycle of a pre
29340 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
29350 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 object usually g
29360 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a oes like this:.*
29370 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ol>.** <li
29380 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65 > Create the pre
29390 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
293a0 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 object using [sq
293b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
293c0 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e ()]..** <li> Bin
293d0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 d values to [par
293e0 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 ameters] using t
293f0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
29400 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 *().** inte
29410 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 rfaces..** <li>
29420 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 Run the SQL by c
29430 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
29440 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d step()] one or m
29450 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c ore times..** <l
29460 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65 i> Reset the pre
29470 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
29480 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 using [sqlite3_r
29490 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 eset()] then go
294a0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 back.** to
294b0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 step 2. Do this
294c0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 zero or more ti
294d0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 mes..** <li> Des
294e0 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 troy the object
294f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
29500 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c inalize()]..** <
29510 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 /ol>.*/.typedef
29520 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 struct sqlite3_s
29530 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 tmt sqlite3_stmt
29540 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
29550 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 F: Run-time Limi
29560 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ts.** METHOD: sq
29570 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 lite3.**.** ^(Th
29580 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c is interface all
29590 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ows the size of
295a0 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 various construc
295b0 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 ts to be limited
295c0 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 .** on a connect
295d0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f ion by connectio
295e0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 n basis. The fi
295f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
29600 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 the.** [databas
29610 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 e connection] wh
29620 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 ose limit is to
29630 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 be set or querie
29640 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e d. The.** secon
29650 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f d parameter is o
29660 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 ne of the [limit
29670 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 categories] tha
29680 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c t define a.** cl
29690 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 ass of construct
296a0 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d s to be size lim
296b0 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 ited. The third
296c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
296d0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 e.** new limit f
296e0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 or that construc
296f0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 t.)^.**.** ^If t
29700 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 he new limit is
29710 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 a negative numbe
29720 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 r, the limit is
29730 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 unchanged..** ^(
29740 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 For each limit c
29750 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c ategory SQLITE_L
29760 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e IMIT_<i>NAME</i>
29770 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 there is a .**
29780 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 [limits | hard u
29790 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 pper bound].** s
297a0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 et at compile-ti
297b0 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f me by a C prepro
297c0 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c cessor macro cal
297d0 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c led.** [limits |
297e0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e SQLITE_MAX_<i>N
297f0 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 AME</i>]..** (Th
29800 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 e "_LIMIT_" in t
29810 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 he name is chang
29820 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 ed to "_MAX_".))
29830 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 ^.** ^Attempts t
29840 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d o increase a lim
29850 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 it above its har
29860 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 d upper bound ar
29870 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 e.** silently tr
29880 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 uncated to the h
29890 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e ard upper bound.
298a0 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 .**.** ^Regardle
298b0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ss of whether or
298c0 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 not the limit w
298d0 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 as changed, the
298e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d .** [sqlite3_lim
298f0 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 it()] interface
29900 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f returns the prio
29910 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c r value of the l
29920 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c imit..** ^Hence,
29930 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 to find the cur
29940 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 rent value of a
29950 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 limit without ch
29960 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 anging it,.** si
29970 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 mply invoke this
29980 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 interface with
29990 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
299a0 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a ter set to -1..*
299b0 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 *.** Run-time li
299c0 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 mits are intende
299d0 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 d for use in app
299e0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d lications that m
299f0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 anage.** both th
29a00 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c eir own internal
29a10 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c database and al
29a20 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 so databases tha
29a30 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 t are controlled
29a40 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 .** by untrusted
29a50 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 external source
29a60 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 s. An example a
29a70 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 pplication might
29a80 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f be a.** web bro
29a90 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 wser that has it
29aa0 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 s own databases
29ab0 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 for storing hist
29ac0 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 ory and.** separ
29ad0 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f ate databases co
29ae0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 ntrolled by Java
29af0 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 Script applicati
29b00 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a ons downloaded.*
29b10 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e * off the Intern
29b20 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 et. The interna
29b30 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 l databases can
29b40 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 be given the.**
29b50 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c large, default l
29b60 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 imits. Database
29b70 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 s managed by ext
29b80 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 ernal sources ca
29b90 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 n.** be given mu
29ba0 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 ch smaller limit
29bb0 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 s designed to pr
29bc0 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f event a denial o
29bd0 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 f service.** att
29be0 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 ack. Developers
29bf0 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 might also want
29c00 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c to use the [sql
29c10 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
29c20 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 zer()].** interf
29c30 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 ace to further c
29c40 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 ontrol untrusted
29c50 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 SQL. The size
29c60 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a of the database.
29c70 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e ** created by an
29c80 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 untrusted scrip
29c90 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e t can be contain
29ca0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 ed using the.**
29cb0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d [max_page_count]
29cc0 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a [PRAGMA]..**.**
29cd0 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 New run-time li
29ce0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d mit categories m
29cf0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
29d00 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a uture releases..
29d10 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c */.int sqlite3_l
29d20 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 imit(sqlite3*, i
29d30 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 nt id, int newVa
29d40 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
29d50 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 REF: Run-Time Li
29d60 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a mit Categories.*
29d70 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d * KEYWORDS: {lim
29d80 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c it category} {*l
29d90 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d imit categories}
29da0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
29db0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 stants define va
29dc0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 rious performanc
29dd0 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 e limits.** that
29de0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 can be lowered
29df0 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e at run-time usin
29e00 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 g [sqlite3_limit
29e10 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f ()]..** The syno
29e20 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e psis of the mean
29e30 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 ings of the vari
29e40 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 ous limits is sh
29e50 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 own below..** Ad
29e60 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
29e70 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c tion is availabl
29e80 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c e at [limits | L
29e90 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d imits in SQLite]
29ea0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ..**.** <dl>.**
29eb0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c [[SQLITE_LIMIT_L
29ec0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 ENGTH]] ^(<dt>SQ
29ed0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
29ee0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
29ef0 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f e maximum size o
29f00 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 f any string or
29f10 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f BLOB or table ro
29f20 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e w, in bytes.<dd>
29f30 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
29f40 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
29f50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 TH]] ^(<dt>SQLIT
29f60 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
29f70 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
29f80 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
29f90 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 h of an SQL stat
29fa0 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e ement, in bytes.
29fb0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
29fc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c SQLITE_LIMIT_COL
29fd0 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 UMN]] ^(<dt>SQLI
29fe0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c TE_LIMIT_COLUMN<
29ff0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
2a000 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
2a010 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 f columns in a t
2a020 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 able definition
2a030 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 or in the.** res
2a040 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 ult set of a [SE
2a050 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 LECT] or the max
2a060 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 imum number of c
2a070 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 olumns in an ind
2a080 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f ex.** or in an O
2a090 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 RDER BY or GROUP
2a0a0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e BY clause.</dd>
2a0b0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
2a0c0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 E_LIMIT_EXPR_DEP
2a0d0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 TH]] ^(<dt>SQLIT
2a0e0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 E_LIMIT_EXPR_DEP
2a0f0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
2a100 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 he maximum depth
2a110 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 of the parse tr
2a120 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 ee on any expres
2a130 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a sion.</dd>)^.**.
2a140 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
2a150 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 T_COMPOUND_SELEC
2a160 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 T]] ^(<dt>SQLITE
2a170 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f _LIMIT_COMPOUND_
2a180 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c SELECT</dt>.** <
2a190 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
2a1a0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 umber of terms i
2a1b0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c n a compound SEL
2a1c0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f ECT statement.</
2a1d0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
2a1e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f LITE_LIMIT_VDBE_
2a1f0 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 OP]] ^(<dt>SQLIT
2a200 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c E_LIMIT_VDBE_OP<
2a210 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
2a220 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
2a230 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 f instructions i
2a240 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 n a virtual mach
2a250 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 ine program.** u
2a260 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 sed to implement
2a270 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
2a280 74 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f t. If [sqlite3_
2a290 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
2a2a0 0a 2a 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65 .** the equivale
2a2b0 6e 74 20 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f nt tries to allo
2a2c0 63 61 74 65 20 73 70 61 63 65 20 66 6f 72 20 6d cate space for m
2a2d0 6f 72 65 20 74 68 61 6e 20 74 68 69 73 20 6d 61 ore than this ma
2a2e0 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e ny opcodes.** in
2a2f0 20 61 20 73 69 6e 67 6c 65 20 70 72 65 70 61 72 a single prepar
2a300 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e ed statement, an
2a310 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 SQLITE_NOMEM er
2a320 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ror is returned.
2a330 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
2a340 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
2a350 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 CTION_ARG]] ^(<d
2a360 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 t>SQLITE_LIMIT_F
2a370 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e UNCTION_ARG</dt>
2a380 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
2a390 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 mum number of ar
2a3a0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e guments on a fun
2a3b0 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ction.</dd>)^.**
2a3c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
2a3d0 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 IT_ATTACHED]] ^(
2a3e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
2a3f0 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a _ATTACHED</dt>.*
2a400 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
2a410 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 m number of [ATT
2a420 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 ACH | attached d
2a430 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 atabases].)^</dd
2a440 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
2a450 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 _LIMIT_LIKE_PATT
2a460 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 ERN_LENGTH]].**
2a470 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
2a480 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f IT_LIKE_PATTERN_
2a490 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c LENGTH</dt>.** <
2a4a0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c dd>The maximum l
2a4b0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 ength of the pat
2a4c0 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f tern argument to
2a4d0 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a the [LIKE] or.*
2a4e0 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f * [GLOB] operato
2a4f0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a rs.</dd>)^.**.**
2a500 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
2a510 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d VARIABLE_NUMBER]
2a520 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 ].** ^(<dt>SQLIT
2a530 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
2a540 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 _NUMBER</dt>.**
2a550 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
2a560 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 index number of
2a570 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 any [parameter]
2a580 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d in an SQL statem
2a590 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 ent.)^.**.** [[S
2a5a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 QLITE_LIMIT_TRIG
2a5b0 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 GER_DEPTH]] ^(<d
2a5c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 t>SQLITE_LIMIT_T
2a5d0 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 RIGGER_DEPTH</dt
2a5e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
2a5f0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 imum depth of re
2a600 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 cursion for trig
2a610 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a gers.</dd>)^.**.
2a620 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
2a630 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 T_WORKER_THREADS
2a640 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
2a650 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 LIMIT_WORKER_THR
2a660 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 EADS</dt>.** <dd
2a670 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
2a680 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 ber of auxiliary
2a690 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 worker threads
2a6a0 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a that a single.**
2a6b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2a6c0 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e ment] may start.
2a6d0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e </dd>)^.** </dl>
2a6e0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
2a6f0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 TE_LIMIT_LENGTH
2a700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2a710 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
2a720 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 ITE_LIMIT_SQL_LE
2a730 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 NGTH
2a740 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
2a750 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d LITE_LIMIT_COLUM
2a760 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 N
2a770 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
2a780 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 QLITE_LIMIT_EXPR
2a790 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 _DEPTH
2a7a0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 3.#define
2a7b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d SQLITE_LIMIT_COM
2a7c0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 POUND_SELECT
2a7d0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 4.#define
2a7e0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 SQLITE_LIMIT_VD
2a7f0 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 BE_OP
2a800 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 5.#defin
2a810 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 e SQLITE_LIMIT_F
2a820 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 UNCTION_ARG
2a830 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6.#defi
2a840 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
2a850 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 ATTACHED
2a860 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 7.#def
2a870 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
2a880 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 _LIKE_PATTERN_LE
2a890 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 NGTH 8.#de
2a8a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
2a8b0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
2a8c0 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 R 9.#d
2a8d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
2a8e0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 IT_TRIGGER_DEPTH
2a8f0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 10.#
2a900 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
2a910 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 MIT_WORKER_THREA
2a920 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a DS 11.
2a930 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2a940 20 50 72 65 70 61 72 65 20 46 6c 61 67 73 0a 2a Prepare Flags.*
2a950 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
2a960 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 ants define vari
2a970 6f 75 73 20 66 6c 61 67 73 20 74 68 61 74 20 63 ous flags that c
2a980 61 6e 20 62 65 20 70 61 73 73 65 64 20 69 6e 74 an be passed int
2a990 6f 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67 73 22 o.** "prepFlags"
2a9a0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 parameter of th
2a9b0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 e [sqlite3_prepa
2a9c0 72 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 re_v3()] and.**
2a9d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2a9e0 31 36 5f 76 33 28 29 5d 20 69 6e 74 65 72 66 61 16_v3()] interfa
2a9f0 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 ces..**.** New f
2aa00 6c 61 67 73 20 6d 61 79 20 62 65 20 61 64 64 65 lags may be adde
2aa10 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
2aa20 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
2aa30 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b **.** <dl>.** [[
2aa40 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 SQLITE_PREPARE_P
2aa50 45 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 ERSISTENT]] ^(<d
2aa60 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 t>SQLITE_PREPARE
2aa70 5f 50 45 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e _PERSISTENT</dt>
2aa80 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 .** <dd>The SQLI
2aa90 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 TE_PREPARE_PERSI
2aaa0 53 54 45 4e 54 20 66 6c 61 67 20 69 73 20 61 20 STENT flag is a
2aab0 68 69 6e 74 20 74 6f 20 74 68 65 20 71 75 65 72 hint to the quer
2aac0 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 y planner.** tha
2aad0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 t the prepared s
2aae0 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 tatement will be
2aaf0 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 61 20 retained for a
2ab00 6c 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a long time and.**
2ab10 20 70 72 6f 62 61 62 6c 79 20 72 65 75 73 65 64 probably reused
2ab20 20 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e many times.)^ ^
2ab30 57 69 74 68 6f 75 74 20 74 68 69 73 20 66 6c 61 Without this fla
2ab40 67 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 g, [sqlite3_prep
2ab50 61 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 are_v3()].** and
2ab60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2ab70 65 31 36 5f 76 33 28 29 5d 20 61 73 73 75 6d 65 e16_v3()] assume
2ab80 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 that the prepar
2ab90 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c ed statement wil
2aba0 6c 20 0a 2a 2a 20 62 65 20 75 73 65 64 20 6a 75 l .** be used ju
2abb0 73 74 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f st once or at mo
2abc0 73 74 20 61 20 66 65 77 20 74 69 6d 65 73 20 61 st a few times a
2abd0 6e 64 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65 nd then destroye
2abe0 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 d using.** [sqli
2abf0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2ac00 72 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e relatively soon.
2ac10 20 54 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 The current imp
2ac20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63 74 73 lementation acts
2ac30 0a 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 .** on this hint
2ac40 20 62 79 20 61 76 6f 69 64 69 6e 67 20 74 68 65 by avoiding the
2ac50 20 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 use of [lookasi
2ac60 64 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73 de memory] so as
2ac70 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 not to.** deple
2ac80 74 65 20 74 68 65 20 6c 69 6d 69 74 65 64 20 73 te the limited s
2ac90 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 tore of lookasid
2aca0 65 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75 72 65 e memory. Future
2acb0 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 versions of.**
2acc0 53 51 4c 69 74 65 20 6d 61 79 20 61 63 74 20 6f SQLite may act o
2acd0 6e 20 74 68 69 73 20 68 69 6e 74 20 64 69 66 66 n this hint diff
2ace0 65 72 65 6e 74 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c erently..** </dl
2acf0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
2ad00 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 ITE_PREPARE_PERS
2ad10 49 53 54 45 4e 54 20 20 20 20 20 20 20 20 20 20 ISTENT
2ad20 20 20 20 20 30 78 30 31 0a 0a 2f 2a 0a 2a 2a 20 0x01../*.**
2ad30 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c CAPI3REF: Compil
2ad40 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 ing An SQL State
2ad50 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ment.** KEYWORDS
2ad60 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 : {SQL statement
2ad70 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 compiler}.** ME
2ad80 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
2ad90 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 CONSTRUCTOR: sq
2ada0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
2adb0 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 To execute an S
2adc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 74 QL statement, it
2add0 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 must first be c
2ade0 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 ompiled into a b
2adf0 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 yte-code.** prog
2ae00 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 ram using one of
2ae10 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e these routines.
2ae20 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65 72 20 77 Or, in other w
2ae30 6f 72 64 73 2c 20 74 68 65 73 65 20 72 6f 75 74 ords, these rout
2ae40 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63 6f 6e 73 ines.** are cons
2ae50 74 72 75 63 74 6f 72 73 20 66 6f 72 20 74 68 65 tructors for the
2ae60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2ae70 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a ment] object..**
2ae80 0a 2a 2a 20 54 68 65 20 70 72 65 66 65 72 72 65 .** The preferre
2ae90 64 20 72 6f 75 74 69 6e 65 20 74 6f 20 75 73 65 d routine to use
2aea0 20 69 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 is [sqlite3_pre
2aeb0 70 61 72 65 5f 76 32 28 29 5d 2e 20 20 54 68 65 pare_v2()]. The
2aec0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
2aed0 70 61 72 65 28 29 5d 20 69 6e 74 65 72 66 61 63 pare()] interfac
2aee0 65 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 e is legacy and
2aef0 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 should be avoide
2af00 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 d..** [sqlite3_p
2af10 72 65 70 61 72 65 5f 76 33 28 29 5d 20 68 61 73 repare_v3()] has
2af20 20 61 6e 20 65 78 74 72 61 20 22 70 72 65 70 46 an extra "prepF
2af30 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20 74 68 61 lags" option tha
2af40 74 20 69 73 20 75 73 65 64 0a 2a 2a 20 66 6f 72 t is used.** for
2af50 20 73 70 65 63 69 61 6c 20 70 75 72 70 6f 73 65 special purpose
2af60 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 73 65 s..**.** The use
2af70 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20 69 6e of the UTF-8 in
2af80 74 65 72 66 61 63 65 73 20 69 73 20 70 72 65 66 terfaces is pref
2af90 65 72 72 65 64 2c 20 61 73 20 53 51 4c 69 74 65 erred, as SQLite
2afa0 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f currently.** do
2afb0 65 73 20 61 6c 6c 20 70 61 72 73 69 6e 67 20 75 es all parsing u
2afc0 73 69 6e 67 20 55 54 46 2d 38 2e 20 20 54 68 65 sing UTF-8. The
2afd0 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61 63 UTF-16 interfac
2afe0 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a es are provided.
2aff0 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65 6e 69 65 ** as a convenie
2b000 6e 63 65 2e 20 20 54 68 65 20 55 54 46 2d 31 36 nce. The UTF-16
2b010 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b interfaces work
2b020 20 62 79 20 63 6f 6e 76 65 72 74 69 6e 67 20 74 by converting t
2b030 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74 65 78 74 he.** input text
2b040 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20 74 68 65 into UTF-8, the
2b050 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 n invoking the c
2b060 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 55 54 46 orresponding UTF
2b070 2d 38 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a -8 interface..**
2b080 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
2b090 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 gument, "db", is
2b0a0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
2b0b0 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 nection] obtaine
2b0c0 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f d from a.** prio
2b0d0 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c r successful cal
2b0e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 l to [sqlite3_op
2b0f0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
2b100 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a open_v2()] or.**
2b110 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
2b120 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 ()]. The databa
2b130 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 se connection mu
2b140 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e st not have been
2b150 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 closed..**.** T
2b160 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
2b170 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 nt, "zSql", is t
2b180 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 he statement to
2b190 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 be compiled, enc
2b1a0 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 oded.** as eithe
2b1b0 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 r UTF-8 or UTF-1
2b1c0 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6. The sqlite3_
2b1d0 70 72 65 70 61 72 65 28 29 2c 20 73 71 6c 69 74 prepare(), sqlit
2b1e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c e3_prepare_v2(),
2b1f0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f .** and sqlite3_
2b200 70 72 65 70 61 72 65 5f 76 33 28 29 0a 2a 2a 20 prepare_v3().**
2b210 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 interfaces use U
2b220 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 TF-8, and sqlite
2b230 33 5f 70 72 65 70 61 72 65 31 36 28 29 2c 20 73 3_prepare16(), s
2b240 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2b250 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 _v2(),.** and sq
2b260 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2b270 76 33 28 29 20 75 73 65 20 55 54 46 2d 31 36 2e v3() use UTF-16.
2b280 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e .**.** ^If the n
2b290 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 Byte argument is
2b2a0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
2b2b0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 zSql is read up
2b2c0 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 to the.** first
2b2d0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
2b2e0 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f ^If nByte is po
2b2f0 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 sitive, then it
2b300 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 is the.** number
2b310 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66 of bytes read f
2b320 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e rom zSql. ^If n
2b330 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 Byte is zero, th
2b340 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a en no prepared.*
2b350 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67 * statement is g
2b360 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 enerated..** If
2b370 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 the caller knows
2b380 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 that the suppli
2b390 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c ed string is nul
2b3a0 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 -terminated, the
2b3b0 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 n.** there is a
2b3c0 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 small performanc
2b3d0 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70 e advantage to p
2b3e0 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 assing an nByte
2b3f0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a parameter that.*
2b400 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 * is the number
2b410 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
2b420 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e input string <i>
2b430 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a including</i>.**
2b440 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 the nul-termina
2b450 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 tor..**.** ^If p
2b460 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c zTail is not NUL
2b470 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 L then *pzTail i
2b480 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 s made to point
2b490 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 to the first byt
2b4a0 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e e.** past the en
2b4b0 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 d of the first S
2b4c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 QL statement in
2b4d0 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 zSql. These rou
2b4e0 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f tines only.** co
2b4f0 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 mpile the first
2b500 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 statement in zSq
2b510 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 l, so *pzTail is
2b520 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 left pointing t
2b530 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e o.** what remain
2b540 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a s uncompiled..**
2b550 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 .** ^*ppStmt is
2b560 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f left pointing to
2b570 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 a compiled [pre
2b580 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2b590 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 that can be.**
2b5a0 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b executed using [
2b5b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e sqlite3_step()].
2b5c0 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 ^If there is a
2b5d0 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 n error, *ppStmt
2b5e0 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 is set.** to NU
2b5f0 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 LL. ^If the inp
2b600 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 ut text contains
2b610 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 no SQL (if the
2b620 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 input is an empt
2b630 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 y.** string or a
2b640 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a comment) then *
2b650 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f ppStmt is set to
2b660 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 NULL..** The ca
2b670 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 lling procedure
2b680 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
2b690 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 or deleting the
2b6a0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 compiled.** SQL
2b6b0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 statement using
2b6c0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2b6d0 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 e()] after it ha
2b6e0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 s finished with
2b6f0 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 it..** ppStmt ma
2b700 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a y not be NULL..*
2b710 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 *.** ^On success
2b720 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 , the sqlite3_pr
2b730 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f epare() family o
2b740 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 f routines retur
2b750 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a n [SQLITE_OK];.*
2b760 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b * otherwise an [
2b770 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
2b780 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 eturned..**.** T
2b790 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 he sqlite3_prepa
2b7a0 72 65 5f 76 32 28 29 2c 20 73 71 6c 69 74 65 33 re_v2(), sqlite3
2b7b0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 2c 20 73 _prepare_v3(), s
2b7c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2b7d0 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 _v2(),.** and sq
2b7e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2b7f0 76 33 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 v3() interfaces
2b800 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 are recommended
2b810 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 for all new prog
2b820 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64 rams..** The old
2b830 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 er interfaces (s
2b840 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
2b850 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
2b860 70 61 72 65 31 36 28 29 29 0a 2a 2a 20 61 72 65 pare16()).** are
2b870 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 retained for ba
2b880 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
2b890 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 ility, but their
2b8a0 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 use is discoura
2b8b0 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 ged..** ^In the
2b8c0 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 2c "vX" interfaces,
2b8d0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
2b8e0 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 atement.** that
2b8f0 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 is returned (the
2b900 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 [sqlite3_stmt]
2b910 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 object) contains
2b920 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a a copy of the.*
2b930 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 * original SQL t
2b940 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 ext. This causes
2b950 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 the [sqlite3_st
2b960 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ep()] interface
2b970 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 to.** behave dif
2b980 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 ferently in thre
2b990 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f e ways:.**.** <o
2b9a0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 l>.** <li>.** ^I
2b9b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 f the database s
2b9c0 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 chema changes, i
2b9d0 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e nstead of return
2b9e0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 ing [SQLITE_SCHE
2b9f0 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 MA] as it.** alw
2ba00 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 ays used to do,
2ba10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2ba20 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 will automatica
2ba30 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 lly recompile th
2ba40 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 e SQL.** stateme
2ba50 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 nt and try to ru
2ba60 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d n it again. As m
2ba70 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d any as [SQLITE_M
2ba80 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d AX_SCHEMA_RETRY]
2ba90 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c .** retries will
2baa0 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 occur before sq
2bab0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 lite3_step() giv
2bac0 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e es up and return
2bad0 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c s an error..** <
2bae0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a /li>.**.** <li>.
2baf0 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f ** ^When an erro
2bb00 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 r occurs, [sqlit
2bb10 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
2bb20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 return one of th
2bb30 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 e detailed.** [e
2bb40 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b rror codes] or [
2bb50 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
2bb60 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 odes]. ^The leg
2bb70 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 acy behavior was
2bb80 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 that.** [sqlite
2bb90 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 3_step()] would
2bba0 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 only return a ge
2bbb0 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 neric [SQLITE_ER
2bbc0 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 ROR] result code
2bbd0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c .** and the appl
2bbe0 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 ication would ha
2bbf0 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 ve to make a sec
2bc00 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ond call to [sql
2bc10 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a ite3_reset()].**
2bc20 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e in order to fin
2bc30 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 d the underlying
2bc40 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 cause of the pr
2bc50 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 oblem. With the
2bc60 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 "v2" prepare.**
2bc70 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 interfaces, the
2bc80 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f underlying reaso
2bc90 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 n for the error
2bca0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 is returned imme
2bcb0 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 diately..** </li
2bcc0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 >.**.** <li>.**
2bcd0 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 ^If the specific
2bce0 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 value bound to
2bcf0 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 [parameter | hos
2bd00 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 t parameter] in
2bd10 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c the .** WHERE cl
2bd20 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 ause might influ
2bd30 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 ence the choice
2bd40 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f of query plan fo
2bd50 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a r a statement,.*
2bd60 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 * then the state
2bd70 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 ment will be aut
2bd80 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d omatically recom
2bd90 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 piled, as if the
2bda0 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 re had been .**
2bdb0 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c a schema change,
2bdc0 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b on the first [
2bdd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2bde0 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 call following a
2bdf0 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 ny change.** to
2be00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
2be10 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 d_text | binding
2be20 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 s] of that [para
2be30 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 meter]. .** ^The
2be40 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 specific value
2be50 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 of WHERE-clause
2be60 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 [parameter] migh
2be70 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 t influence the
2be80 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 .** choice of qu
2be90 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 ery plan if the
2bea0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
2beb0 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 left-hand side
2bec0 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f of a [LIKE].** o
2bed0 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f r [GLOB] operato
2bee0 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 r or if the para
2bef0 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 meter is compare
2bf00 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 d to an indexed
2bf10 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 column.** and th
2bf20 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 e [SQLITE_ENABLE
2bf30 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d _STAT3] compile-
2bf40 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 time option is e
2bf50 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e nabled..** </li>
2bf60 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ol>.**.**
2bf70 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72 65 70 <p>^sqlite3_prep
2bf80 61 72 65 5f 76 33 28 29 20 64 69 66 66 65 72 73 are_v3() differs
2bf90 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72 from sqlite3_pr
2bfa0 65 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20 epare_v2() only
2bfb0 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65 in having.** the
2bfc0 20 65 78 74 72 61 20 70 72 65 70 46 6c 61 67 73 extra prepFlags
2bfd0 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 parameter, whic
2bfe0 68 20 69 73 20 61 20 62 69 74 20 61 72 72 61 79 h is a bit array
2bff0 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a consisting of z
2c000 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f ero or.** more o
2c010 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 50 52 f the [SQLITE_PR
2c020 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 EPARE_PERSISTENT
2c030 7c 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f |SQLITE_PREPARE_
2c040 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a *] flags. ^The.
2c050 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 ** sqlite3_prepa
2c060 72 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 re_v2() interfac
2c070 65 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 e works exactly
2c080 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 the same as.** s
2c090 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2c0a0 33 28 29 20 77 69 74 68 20 61 20 7a 65 72 6f 20 3() with a zero
2c0b0 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65 prepFlags parame
2c0c0 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ter..*/.int sqli
2c0d0 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 te3_prepare(. s
2c0e0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
2c0f0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
2c100 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
2c110 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
2c120 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
2c130 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 atement, UTF-8 e
2c140 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
2c150 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
2c160 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
2c170 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
2c180 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
2c190 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
2c1a0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
2c1b0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
2c1c0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a . const char **
2c1d0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
2c1e0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
2c1f0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
2c200 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 zSql */.);.int s
2c210 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2c220 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
2c230 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
2c240 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
2c250 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
2c260 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
2c270 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
2c280 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a TF-8 encoded */.
2c290 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
2c2a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
2c2b0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
2c2c0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
2c2d0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
2c2e0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
2c2f0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
2c300 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
2c310 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 har **pzTail
2c320 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
2c330 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
2c340 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
2c350 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 .int sqlite3_pre
2c360 70 61 72 65 5f 76 33 28 0a 20 20 73 71 6c 69 74 pare_v3(. sqlit
2c370 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
2c380 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
2c390 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
2c3a0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 char *zSql,
2c3b0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
2c3c0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 ent, UTF-8 encod
2c3d0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
2c3e0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
2c3f0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
2c400 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
2c410 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 es. */. unsigne
2c420 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c d int prepFlags,
2c430 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 /* Zero or more
2c440 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f SQLITE_PREPARE_
2c450 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 flags */. sqli
2c460 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
2c470 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
2c480 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
2c490 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 const char **p
2c4a0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
2c4b0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
2c4c0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
2c4d0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 Sql */.);.int sq
2c4e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
2c4f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
2c500 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
2c510 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f tabase handle */
2c520 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a . const void *z
2c530 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 Sql, /* SQ
2c540 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 L statement, UTF
2c550 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 -16 encoded */.
2c560 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 int nByte,
2c570 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
2c580 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 mum length of zS
2c590 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
2c5a0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
2c5b0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
2c5c0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
2c5d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
2c5e0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 id **pzTail
2c5f0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
2c600 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
2c610 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
2c620 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
2c630 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 are16_v2(. sqli
2c640 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
2c650 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
2c660 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
2c670 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 t void *zSql,
2c680 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
2c690 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 ment, UTF-16 enc
2c6a0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
2c6b0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
2c6c0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
2c6d0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
2c6e0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
2c6f0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
2c700 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
2c710 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
2c720 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a const void **pz
2c730 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
2c740 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
2c750 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
2c760 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c ql */.);.int sql
2c770 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
2c780 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 3(. sqlite3 *db
2c790 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
2c7a0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
2c7b0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
2c7c0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
2c7d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
2c7e0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
2c7f0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
2c800 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
2c810 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
2c820 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
2c830 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 /. unsigned int
2c840 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a prepFlags, /* Z
2c850 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 ero or more SQLI
2c860 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 67 TE_PREPARE_ flag
2c870 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 s */. sqlite3_s
2c880 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
2c890 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
2c8a0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
2c8b0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c st void **pzTail
2c8c0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
2c8d0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
2c8e0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
2c8f0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
2c900 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 3REF: Retrieving
2c910 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a Statement SQL.*
2c920 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
2c930 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
2c940 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 e sqlite3_sql(P)
2c950 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2c960 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
2c970 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 55 54 a copy of the UT
2c980 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 F-8.** SQL text
2c990 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 5b used to create [
2c9a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2c9b0 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73 0a 2a nt] P if P was.*
2c9c0 2a 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 * created by [sq
2c9d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2c9e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 ()], [sqlite3_pr
2c9f0 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 epare_v3()],.**
2ca00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2ca10 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 16_v2()], or [sq
2ca20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2ca30 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 v3()]..** ^The s
2ca40 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f qlite3_expanded_
2ca50 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 sql(P) interface
2ca60 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
2ca70 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a er to a UTF-8.**
2ca80 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 string containi
2ca90 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78 74 20 ng the SQL text
2caa0 6f 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 of prepared stat
2cab0 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20 ement P with.**
2cac0 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 [bound parameter
2cad0 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a s] expanded..**.
2cae0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 ** ^(For example
2caf0 2c 20 69 66 20 61 20 70 72 65 70 61 72 65 64 20 , if a prepared
2cb00 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65 statement is cre
2cb10 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 ated using the S
2cb20 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 QL.** text "SELE
2cb30 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e CT $abc,:xyz" an
2cb40 64 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 24 d if parameter $
2cb50 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 abc is bound to
2cb60 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 integer 2345.**
2cb70 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78 and parameter :x
2cb80 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 yz is unbound, t
2cb90 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 hen sqlite3_sql(
2cba0 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a ) will return.**
2cbb0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 the original st
2cbc0 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61 ring, "SELECT $a
2cbd0 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c bc,:xyz" but sql
2cbe0 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 ite3_expanded_sq
2cbf0 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 l().** will retu
2cc00 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c rn "SELECT 2345,
2cc10 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e NULL".)^.**.** ^
2cc20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 The sqlite3_expa
2cc30 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 nded_sql() inter
2cc40 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c face returns NUL
2cc50 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e L if insufficien
2cc60 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 t memory.** is a
2cc70 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 vailable to hold
2cc80 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 the result, or
2cc90 69 66 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f if the result wo
2cca0 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a uld exceed the.*
2ccb0 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 * the maximum st
2ccc0 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65 ring length dete
2ccd0 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53 rmined by the [S
2cce0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 QLITE_LIMIT_LENG
2ccf0 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 TH]..**.** ^The
2cd00 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 [SQLITE_TRACE_SI
2cd10 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c ZE_LIMIT] compil
2cd20 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 e-time option li
2cd30 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66 mits the size of
2cd40 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 .** bound parame
2cd50 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 ter expansions.
2cd60 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d ^The [SQLITE_OM
2cd70 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c IT_TRACE] compil
2cd80 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e e-time.** option
2cd90 20 63 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f causes sqlite3_
2cda0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 expanded_sql() t
2cdb0 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 o always return
2cdc0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 NULL..**.** ^The
2cdd0 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 string returned
2cde0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 by sqlite3_sql(
2cdf0 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20 62 79 P) is managed by
2ce00 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a SQLite and is.*
2ce10 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 * automatically
2ce20 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 20 70 freed when the p
2ce30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2ce40 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a t is finalized..
2ce50 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72 ** ^The string r
2ce60 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
2ce70 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 e3_expanded_sql(
2ce80 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65 72 P), on the other
2ce90 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 hand,.** is obt
2cea0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
2ceb0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e te3_malloc()] an
2cec0 64 20 6d 75 73 74 20 62 65 20 66 72 65 65 20 62 d must be free b
2ced0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
2cee0 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e 67 20 n.** by passing
2cef0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 it to [sqlite3_f
2cf00 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 ree()]..*/.const
2cf10 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 char *sqlite3_s
2cf20 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ql(sqlite3_stmt
2cf30 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73 *pStmt);.char *s
2cf40 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f qlite3_expanded_
2cf50 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 sql(sqlite3_stmt
2cf60 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
2cf70 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 CAPI3REF: Deter
2cf80 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 mine If An SQL S
2cf90 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 tatement Writes
2cfa0 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 The Database.**
2cfb0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
2cfc0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 stmt.**.** ^The
2cfd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 sqlite3_stmt_rea
2cfe0 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 donly(X) interfa
2cff0 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 ce returns true
2d000 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a (non-zero) if.**
2d010 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 and only if the
2d020 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2d030 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f ment] X makes no
2d040 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 direct changes
2d050 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e to.** the conten
2d060 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 t of the databas
2d070 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f e file..**.** No
2d080 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 te that [applica
2d090 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
2d0a0 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a functions] or.*
2d0b0 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 * [virtual table
2d0c0 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 s] might change
2d0d0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 the database ind
2d0e0 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 irectly as a sid
2d0f0 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e e effect. .** ^
2d100 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 (For example, if
2d110 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
2d120 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 defines a functi
2d130 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 on "eval()" that
2d140 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 .** calls [sqli
2d150 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 te3_exec()], the
2d160 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 n the following
2d170 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f SQL statement wo
2d180 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 uld.** change th
2d190 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
2d1a0 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 through side-eff
2d1b0 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f ects:.**.** <blo
2d1c0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
2d1d0 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 SELECT eval(
2d1e0 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 'DELETE FROM t1'
2d1f0 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f ) FROM t2;.** </
2d200 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
2d210 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 >.**.** But beca
2d220 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d use the [SELECT]
2d230 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 statement does
2d240 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 not change the d
2d250 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 atabase file.**
2d260 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 directly, sqlite
2d270 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
2d280 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 ) would still re
2d290 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a turn true.)^.**.
2d2a0 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 ** ^Transaction
2d2b0 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e control statemen
2d2c0 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 ts such as [BEGI
2d2d0 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 N], [COMMIT], [R
2d2e0 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 OLLBACK],.** [SA
2d2f0 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 VEPOINT], and [R
2d300 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 ELEASE] cause sq
2d310 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f lite3_stmt_reado
2d320 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 nly() to return
2d330 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 true,.** since t
2d340 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 he statements th
2d350 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 emselves do not
2d360 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 actually modify
2d370 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 the database but
2d380 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 .** rather they
2d390 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 control the timi
2d3a0 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 ng of when other
2d3b0 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 statements modi
2d3c0 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 fy the .** datab
2d3d0 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 ase. ^The [ATTA
2d3e0 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d CH] and [DETACH]
2d3f0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f statements also
2d400 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 cause.** sqlite
2d410 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
2d420 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 ) to return true
2d430 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 since, while th
2d440 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a ose statements.*
2d450 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e * change the con
2d460 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 figuration of a
2d470 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2d480 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 ion, they do not
2d490 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 make .** change
2d4a0 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 s to the content
2d4b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
2d4c0 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a files on disk..
2d4d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2d4e0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 stmt_readonly()
2d4f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2d500 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45 47 49 s true for [BEGI
2d510 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 N] since.** [BEG
2d520 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74 73 20 IN] merely sets
2d530 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20 internal flags,
2d540 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e 7c 42 but the [BEGIN|B
2d550 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20 EGIN IMMEDIATE]
2d560 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 and.** [BEGIN|BE
2d570 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d 20 63 GIN EXCLUSIVE] c
2d580 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75 63 68 ommands do touch
2d590 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e the database an
2d5a0 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f d so.** sqlite3_
2d5b0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 stmt_readonly()
2d5c0 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 66 6f returns false fo
2d5d0 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 r those commands
2d5e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2d5f0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 _stmt_readonly(s
2d600 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
2d610 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
2d620 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 3REF: Determine
2d630 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 If A Prepared St
2d640 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e atement Has Been
2d650 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 Reset.** METHOD
2d660 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
2d670 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2d680 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 3_stmt_busy(S) i
2d690 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
2d6a0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 true (non-zero)
2d6b0 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 if the.** [prep
2d6c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2d6d0 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 S has been stepp
2d6e0 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 ed at least once
2d6f0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 using .** [sqli
2d700 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 te3_step(S)] but
2d710 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e has neither run
2d720 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 to completion (
2d730 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c returned.** [SQL
2d740 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b ITE_DONE] from [
2d750 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
2d760 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 ) nor.** been re
2d770 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 set using [sqlit
2d780 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e e3_reset(S)]. ^
2d790 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 The sqlite3_stmt
2d7a0 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 _busy(S).** inte
2d7b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 rface returns fa
2d7c0 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 lse if S is a NU
2d7d0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 LL pointer. If
2d7e0 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e S is not a .** N
2d7f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 ULL pointer and
2d800 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 is not a pointer
2d810 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 to a valid [pre
2d820 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2d830 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e .** object, then
2d840 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
2d850 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 undefined and p
2d860 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 robably undesira
2d870 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ble..**.** This
2d880 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
2d890 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 used in combina
2d8a0 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 tion [sqlite3_ne
2d8b0 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f xt_stmt()].** to
2d8c0 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 locate all prep
2d8d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 ared statements
2d8e0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
2d8f0 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 a database .** c
2d900 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 onnection that a
2d910 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 re in need of be
2d920 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 ing reset. This
2d930 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a can be used,.**
2d940 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e for example, in
2d950 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 diagnostic rout
2d960 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 ines to search f
2d970 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 or prepared .**
2d980 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 statements that
2d990 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 are holding a tr
2d9a0 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a ansaction open..
2d9b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 */.int sqlite3_s
2d9c0 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 tmt_busy(sqlite3
2d9d0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
2d9e0 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 CAPI3REF: Dynami
2d9f0 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 cally Typed Valu
2da00 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 e Object.** KEYW
2da10 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 ORDS: {protected
2da20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 sqlite3_value}
2da30 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c {unprotected sql
2da40 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a ite3_value}.**.*
2da50 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 * SQLite uses th
2da60 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
2da70 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 object to repres
2da80 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a ent all values.*
2da90 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 * that can be st
2daa0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 ored in a databa
2dab0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 se table. SQLite
2dac0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 uses dynamic ty
2dad0 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 ping.** for the
2dae0 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 values it stores
2daf0 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 . ^Values store
2db00 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c d in sqlite3_val
2db10 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 ue objects.** ca
2db20 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 n be integers, f
2db30 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 loating point va
2db40 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 lues, strings, B
2db50 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a LOBs, or NULL..*
2db60 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f *.** An sqlite3_
2db70 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 value object may
2db80 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 be either "prot
2db90 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f ected" or "unpro
2dba0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 tected"..** Some
2dbb0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 interfaces requ
2dbc0 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 ire a protected
2dbd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 sqlite3_value.
2dbe0 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 Other interfaces
2dbf0 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 .** will accept
2dc00 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 either a protect
2dc10 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 ed or an unprote
2dc20 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2dc30 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 ue..** Every int
2dc40 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 erface that acce
2dc50 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 pts sqlite3_valu
2dc60 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 e arguments spec
2dc70 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 ifies.** whether
2dc80 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 or not it requi
2dc90 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 res a protected
2dca0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 sqlite3_value.
2dcb0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f The.** [sqlite3_
2dcc0 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 value_dup()] int
2dcd0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 erface can be us
2dce0 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 ed to construct
2dcf0 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 a new .** protec
2dd00 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2dd10 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 e from an unprot
2dd20 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2dd30 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 lue..**.** The t
2dd40 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 erms "protected"
2dd50 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 and "unprotecte
2dd60 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 d" refer to whet
2dd70 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 her or not.** a
2dd80 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 mutex is held.
2dd90 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 An internal mute
2dda0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 x is held for a
2ddb0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
2ddc0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
2ddd0 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 t but no mutex i
2dde0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e s held for an un
2ddf0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
2de00 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
2de10 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 t. If SQLite is
2de20 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 compiled to be
2de30 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a single-threaded.
2de40 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 ** (with [SQLITE
2de50 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 _THREADSAFE=0] a
2de60 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 nd with [sqlite3
2de70 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 _threadsafe()] r
2de80 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f eturning 0).** o
2de90 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 r if SQLite is r
2dea0 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 un in one of red
2deb0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 uced mutex modes
2dec0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [SQLITE_CON
2ded0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
2dee0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e ] or [SQLITE_CON
2def0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d FIG_MULTITHREAD]
2df00 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 .** then there i
2df10 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e s no distinction
2df20 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 between protect
2df30 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 ed and unprotect
2df40 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 ed.** sqlite3_va
2df50 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 lue objects and
2df60 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 they can be used
2df70 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 interchangeably
2df80 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 . However,.** f
2df90 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 or maximum code
2dfa0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 portability it i
2dfb0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 s recommended th
2dfc0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a at applications.
2dfd0 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 ** still make th
2dfe0 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 e distinction be
2dff0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 tween protected
2e000 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a and unprotected.
2e010 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
2e020 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 objects even wh
2e030 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 en not strictly
2e040 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
2e050 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
2e060 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 ue objects that
2e070 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 are passed as pa
2e080 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 rameters into th
2e090 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
2e0a0 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 ion of [applicat
2e0b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
2e0c0 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 functions] are p
2e0d0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 rotected..** ^Th
2e0e0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
2e0f0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
2e100 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 by.** [sqlite3_c
2e110 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 olumn_value()] i
2e120 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a s unprotected..*
2e130 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 * Unprotected sq
2e140 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
2e150 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 cts may only be
2e160 75 73 65 64 20 61 73 20 61 72 67 75 6d 65 6e 74 used as argument
2e170 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 s.** to [sqlite3
2e180 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d _result_value()]
2e190 2c 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f , [sqlite3_bind_
2e1a0 76 61 6c 75 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a value()], and.**
2e1b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2e1c0 64 75 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b dup()]..** The [
2e1d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
2e1e0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c ob | sqlite3_val
2e1f0 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c ue_type()] famil
2e200 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 y of.** interfac
2e210 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 es require prote
2e220 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2e230 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 ue objects..*/.t
2e240 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
2e250 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71 6c 69 lite3_value sqli
2e260 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a te3_value;../*.*
2e270 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 * CAPI3REF: SQL
2e280 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 Function Context
2e290 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 Object.**.** Th
2e2a0 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 e context in whi
2e2b0 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 ch an SQL functi
2e2c0 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 on executes is s
2e2d0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 tored in an.** s
2e2e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f qlite3_context o
2e2f0 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 bject. ^A point
2e300 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 er to an sqlite3
2e310 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a _context object.
2e320 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 ** is always fir
2e330 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
2e340 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
2e350 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
2e360 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c ns]..** The appl
2e370 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
2e380 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 SQL function imp
2e390 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c lementation will
2e3a0 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f pass this.** po
2e3b0 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e inter through in
2e3c0 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c to calls to [sql
2e3d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 ite3_result_int
2e3e0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 | sqlite3_result
2e3f0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
2e400 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
2e410 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f xt()], [sqlite3_
2e420 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a user_data()],.**
2e430 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 [sqlite3_contex
2e440 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 t_db_handle()],
2e450 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 [sqlite3_get_aux
2e460 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f data()],.** and/
2e470 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f or [sqlite3_set_
2e480 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 auxdata()]..*/.t
2e490 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
2e4a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 lite3_context sq
2e4b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a lite3_context;..
2e4c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2e4d0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 Binding Values T
2e4e0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 o Prepared State
2e4f0 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 ments.** KEYWORD
2e500 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 S: {host paramet
2e510 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 er} {host parame
2e520 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 ters} {host para
2e530 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b meter name}.** K
2e540 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 EYWORDS: {SQL pa
2e550 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 rameter} {SQL pa
2e560 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d rameters} {param
2e570 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a eter binding}.**
2e580 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
2e590 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e _stmt.**.** ^(In
2e5a0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
2e5b0 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f nt text input to
2e5c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2e5d0 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 e_v2()] and its
2e5e0 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 variants,.** lit
2e5f0 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 erals may be rep
2e600 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 laced by a [para
2e610 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 meter] that matc
2e620 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f hes one of follo
2e630 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 wing.** template
2e640 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
2e650 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e <li> ?.** <li>
2e660 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 ?NNN.** <li>
2e670 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 :VVV.** <li> @V
2e680 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 VV.** <li> $VVV
2e690 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
2e6a0 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 In the templates
2e6b0 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 above, NNN repr
2e6c0 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 esents an intege
2e6d0 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e r literal,.** an
2e6e0 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 d VVV represents
2e6f0 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 an alphanumeric
2e700 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 identifier.)^
2e710 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 ^The values of t
2e720 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 hese.** paramete
2e730 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 rs (also called
2e740 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 "host parameter
2e750 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 names" or "SQL p
2e760 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 arameters").** c
2e770 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 an be set using
2e780 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
2e790 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 _*() routines de
2e7a0 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a fined here..**.*
2e7b0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 * ^The first arg
2e7c0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c ument to the sql
2e7d0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f ite3_bind_*() ro
2e7e0 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 utines is always
2e7f0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f .** a pointer to
2e800 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 the [sqlite3_st
2e810 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 mt] object retur
2e820 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c ned from.** [sql
2e830 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2e840 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e )] or its varian
2e850 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ts..**.** ^The s
2e860 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
2e870 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
2e880 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 he SQL parameter
2e890 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e to be set..** ^
2e8a0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c The leftmost SQL
2e8b0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 parameter has a
2e8c0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e n index of 1. ^
2e8d0 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 When the same na
2e8e0 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d med.** SQL param
2e8f0 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 eter is used mor
2e900 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 e than once, sec
2e910 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 ond and subseque
2e920 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 nt.** occurrence
2e930 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 s have the same
2e940 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 index as the fir
2e950 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a st occurrence..*
2e960 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 * ^The index for
2e970 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 named parameter
2e980 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 s can be looked
2e990 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 up using the.**
2e9a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
2e9b0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
2e9c0 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e API if desired.
2e9d0 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 ^The index.**
2e9e0 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d for "?NNN" param
2e9f0 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c eters is the val
2ea00 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 ue of NNN..** ^T
2ea10 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 he NNN value mus
2ea20 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 t be between 1 a
2ea30 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f nd the [sqlite3_
2ea40 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 limit()].** para
2ea50 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 meter [SQLITE_LI
2ea60 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
2ea70 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 BER] (default va
2ea80 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a lue: 999)..**.**
2ea90 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 ^The third argu
2eaa0 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 ment is the valu
2eab0 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 e to bind to the
2eac0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e parameter..** ^
2ead0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 If the third par
2eae0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
2eaf0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 3_bind_text() or
2eb00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
2eb10 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c xt16().** or sql
2eb20 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 ite3_bind_blob()
2eb30 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
2eb40 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 er then the four
2eb50 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 th parameter.**
2eb60 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 is ignored and t
2eb70 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 he end result is
2eb80 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c the same as sql
2eb90 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 ite3_bind_null()
2eba0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f ..**.** ^(In tho
2ebb0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 se routines that
2ebc0 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 have a fourth a
2ebd0 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c rgument, its val
2ebe0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d ue is the.** num
2ebf0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
2ec00 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 the parameter.
2ec10 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 To be clear: the
2ec20 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a value is the.**
2ec30 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 number of <u>by
2ec40 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 tes</u> in the v
2ec50 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 alue, not the nu
2ec60 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 mber of characte
2ec70 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 rs.)^.** ^If the
2ec80 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
2ec90 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e r to sqlite3_bin
2eca0 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 d_text() or sqli
2ecb0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
2ecc0 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 ).** is negative
2ecd0 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 , then the lengt
2ece0 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 h of the string
2ecf0 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 is.** the number
2ed00 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 of bytes up to
2ed10 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 the first zero t
2ed20 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 erminator..** If
2ed30 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
2ed40 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
2ed50 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 _bind_blob() is
2ed60 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a negative, then.*
2ed70 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 * the behavior i
2ed80 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 s undefined..**
2ed90 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 If a non-negativ
2eda0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
2edb0 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 er is provided t
2edc0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 o sqlite3_bind_t
2edd0 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 ext().** or sqli
2ede0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
2edf0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e ) or sqlite3_bin
2ee00 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a d_text64() then.
2ee10 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 ** that paramete
2ee20 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 r must be the by
2ee30 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 te offset.** whe
2ee40 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 re the NUL termi
2ee50 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 nator would occu
2ee60 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 r assuming the s
2ee70 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a tring were NUL.*
2ee80 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 * terminated. I
2ee90 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 f any NUL charac
2eea0 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 ters occur at by
2eeb0 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 te offsets less
2eec0 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c than .** the val
2eed0 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 ue of the fourth
2eee0 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 parameter then
2eef0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 the resulting st
2ef00 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a ring value will.
2ef10 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 ** contain embed
2ef20 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 ded NULs. The r
2ef30 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 esult of express
2ef40 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 ions involving s
2ef50 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 trings.** with e
2ef60 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 mbedded NULs is
2ef70 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
2ef80 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 ^The fifth argu
2ef90 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 ment to the BLOB
2efa0 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 and string bind
2efb0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a ing interfaces.*
2efc0 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f * is a destructo
2efd0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 r used to dispos
2efe0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 e of the BLOB or
2eff0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 .** string after
2f000 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 SQLite has fini
2f010 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e shed with it. ^
2f020 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 The destructor i
2f030 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 s called.** to d
2f040 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c ispose of the BL
2f050 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 OB or string eve
2f060 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f n if the call to
2f070 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e bind API fails.
2f080 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 .** ^If the fift
2f090 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a h argument is.**
2f0a0 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c the special val
2f0b0 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 ue [SQLITE_STATI
2f0c0 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 C], then SQLite
2f0d0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 assumes that the
2f0e0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
2f0f0 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e is in static, un
2f100 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e managed space an
2f110 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 d does not need
2f120 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 to be freed..**
2f130 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 ^If the fifth ar
2f140 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 gument has the v
2f150 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 alue [SQLITE_TRA
2f160 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a NSIENT], then.**
2f170 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 SQLite makes it
2f180 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f s own private co
2f190 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 py of the data i
2f1a0 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f mmediately, befo
2f1b0 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 re.** the sqlite
2f1c0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
2f1d0 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a ne returns..**.*
2f1e0 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 * ^The sixth arg
2f1f0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
2f200 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d _bind_text64() m
2f210 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a ust be one of.**
2f220 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 [SQLITE_UTF8],
2f230 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 [SQLITE_UTF16],
2f240 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d [SQLITE_UTF16BE]
2f250 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 , or [SQLITE_UTF
2f260 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 16LE].** to spec
2f270 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ify the encoding
2f280 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 of the text in
2f290 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
2f2a0 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 ter. If.** the
2f2b0 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 sixth argument t
2f2c0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 o sqlite3_bind_t
2f2d0 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f ext64() is not o
2f2e0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c ne of the.** all
2f2f0 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 owed values show
2f300 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 n above, or if t
2f310 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 he text encoding
2f320 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a is different.**
2f330 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 from the encodi
2f340 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20 ng specified by
2f350 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 the sixth parame
2f360 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 ter, then the be
2f370 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 havior.** is und
2f380 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 efined..**.** ^T
2f390 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
2f3a0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 zeroblob() routi
2f3b0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 ne binds a BLOB
2f3c0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 of length N that
2f3d0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 .** is filled wi
2f3e0 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a th zeroes. ^A z
2f3f0 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 eroblob uses a f
2f400 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d ixed amount of m
2f410 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 emory.** (just a
2f420 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c n integer to hol
2f430 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c d its size) whil
2f440 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 e it is being pr
2f450 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f ocessed..** Zero
2f460 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 blobs are intend
2f470 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 ed to serve as p
2f480 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 laceholders for
2f490 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 BLOBs whose.** c
2f4a0 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 ontent is later
2f4b0 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a written using.**
2f4c0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
2f4d0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 pen | incrementa
2f4e0 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 l BLOB I/O] rout
2f4f0 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 ines..** ^A nega
2f500 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 tive value for t
2f510 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 he zeroblob resu
2f520 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 lts in a zero-le
2f530 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a ngth BLOB..**.**
2f540 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 ^The sqlite3_bi
2f550 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50 nd_pointer(S,I,P
2f560 2c 54 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 61 ,T,D) routine ca
2f570 75 73 65 73 20 74 68 65 20 49 2d 74 68 20 70 61 uses the I-th pa
2f580 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 rameter in.** [p
2f590 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2f5a0 74 5d 20 53 20 74 6f 20 68 61 76 65 20 61 6e 20 t] S to have an
2f5b0 53 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c SQL value of NUL
2f5c0 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f 20 62 L, but to also b
2f5d0 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 e.** associated
2f5e0 77 69 74 68 20 74 68 65 20 70 6f 69 6e 74 65 72 with the pointer
2f5f0 20 50 20 6f 66 20 74 79 70 65 20 54 2e 20 20 5e P of type T. ^
2f600 44 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 D is either a NU
2f610 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a LL pointer or.**
2f620 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
2f630 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 destructor funct
2f640 69 6f 6e 20 66 6f 72 20 50 2e 20 5e 53 51 4c 69 ion for P. ^SQLi
2f650 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 te will invoke t
2f660 68 65 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 he.** destructor
2f670 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65 D with a single
2f680 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 50 20 77 argument of P w
2f690 68 65 6e 20 69 74 20 69 73 20 66 69 6e 69 73 68 hen it is finish
2f6a0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 ed using.** P.
2f6b0 54 68 65 20 54 20 70 61 72 61 6d 65 74 65 72 20 The T parameter
2f6c0 73 68 6f 75 6c 64 20 62 65 20 61 20 73 74 61 74 should be a stat
2f6d0 69 63 20 73 74 72 69 6e 67 2c 20 70 72 65 66 65 ic string, prefe
2f6e0 72 61 62 6c 79 20 61 20 73 74 72 69 6e 67 0a 2a rably a string.*
2f6f0 2a 20 6c 69 74 65 72 61 6c 2e 20 54 68 65 20 73 * literal. The s
2f700 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e qlite3_bind_poin
2f710 74 65 72 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ter() routine is
2f720 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 part of the.**
2f730 5b 70 6f 69 6e 74 65 72 20 70 61 73 73 69 6e 67 [pointer passing
2f740 20 69 6e 74 65 72 66 61 63 65 5d 20 61 64 64 65 interface] adde
2f750 64 20 66 6f 72 20 53 51 4c 69 74 65 20 33 2e 32 d for SQLite 3.2
2f760 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 0.0..**.** ^If a
2f770 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ny of the sqlite
2f780 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
2f790 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 nes are called w
2f7a0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
2f7b0 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 er.** for the [p
2f7c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2f7d0 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 t] or with a pre
2f7e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
2f7f0 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 for which.** [sq
2f800 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 lite3_step()] ha
2f810 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f s been called mo
2f820 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e re recently than
2f830 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2f840 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 )],.** then the
2f850 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e call will return
2f860 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
2f870 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 . If any sqlite
2f880 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 3_bind_().** rou
2f890 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 tine is passed a
2f8a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2f8b0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 ment] that has b
2f8c0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 een finalized, t
2f8d0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 he.** result is
2f8e0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 undefined and pr
2f8f0 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a obably harmful..
2f900 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 **.** ^Bindings
2f910 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 are not cleared
2f920 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
2f930 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 reset()] routine
2f940 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 ..** ^Unbound pa
2f950 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 rameters are int
2f960 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c erpreted as NULL
2f970 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
2f980 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 ite3_bind_* rout
2f990 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c ines return [SQL
2f9a0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
2f9b0 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 ss or an.** [err
2f9c0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 or code] if anyt
2f9d0 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e hing goes wrong.
2f9e0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f .** ^[SQLITE_TOO
2f9f0 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 BIG] might be re
2fa00 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 turned if the si
2fa10 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f ze of a string o
2fa20 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 r BLOB.** exceed
2fa30 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 s limits imposed
2fa40 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d by [sqlite3_lim
2fa50 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 it]([SQLITE_LIMI
2fa60 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a T_LENGTH]) or.**
2fa70 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e [SQLITE_MAX_LEN
2fa80 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 GTH]..** ^[SQLIT
2fa90 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 E_RANGE] is retu
2faa0 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 rned if the para
2fab0 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 meter.** index i
2fac0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 s out of range.
2fad0 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d ^[SQLITE_NOMEM]
2fae0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 is returned if
2faf0 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a malloc() fails..
2fb00 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
2fb10 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
2fb20 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
2fb30 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
2fb40 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
2fb50 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 e()], and [sqlit
2fb60 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2fb70 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 r_index()]..*/.i
2fb80 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2fb90 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d blob(sqlite3_stm
2fba0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 t*, int, const v
2fbb0 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 oid*, int n, voi
2fbc0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e d(*)(void*));.in
2fbd0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 t sqlite3_bind_b
2fbe0 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 lob64(sqlite3_st
2fbf0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
2fc00 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 void*, sqlite3_u
2fc10 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 int64,.
2fc20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
2fc30 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
2fc40 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
2fc50 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
2fc60 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 stmt*, int, doub
2fc70 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 le);.int sqlite3
2fc80 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 _bind_int(sqlite
2fc90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 3_stmt*, int, in
2fca0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f t);.int sqlite3_
2fcb0 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 bind_int64(sqlit
2fcc0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 e3_stmt*, int, s
2fcd0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 qlite3_int64);.i
2fce0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2fcf0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d null(sqlite3_stm
2fd00 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 t*, int);.int sq
2fd10 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 lite3_bind_text(
2fd20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2fd30 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e t,const char*,in
2fd40 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 t,void(*)(void*)
2fd50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
2fd60 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 ind_text16(sqlit
2fd70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
2fd80 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
2fd90 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
2fda0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
2fdb0 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 nd_text64(sqlite
2fdc0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
2fdd0 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 nst char*, sqlit
2fde0 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 e3_uint64,.
2fdf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2fe00 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 void(*)(void
2fe10 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 *), unsigned cha
2fe20 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 r encoding);.int
2fe30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 sqlite3_bind_va
2fe40 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lue(sqlite3_stmt
2fe50 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 *, int, const sq
2fe60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
2fe70 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2fe80 70 6f 69 6e 74 65 72 28 73 71 6c 69 74 65 33 5f pointer(sqlite3_
2fe90 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 stmt*, int, void
2fea0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 76 *, const char*,v
2feb0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
2fec0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
2fed0 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 _zeroblob(sqlite
2fee0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 3_stmt*, int, in
2fef0 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 t n);.int sqlite
2ff00 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 3_bind_zeroblob6
2ff10 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
2ff20 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 int, sqlite3_ui
2ff30 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt64);../*.** CA
2ff40 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f PI3REF: Number O
2ff50 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 f SQL Parameters
2ff60 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
2ff70 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
2ff80 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e This routine can
2ff90 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 be used to find
2ffa0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b the number of [
2ffb0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a SQL parameters].
2ffc0 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 ** in a [prepare
2ffd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 d statement]. S
2ffe0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 QL parameters ar
2fff0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a e tokens of the.
30000 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e ** form "?", "?N
30010 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 NN", ":AAA", "$A
30020 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 AA", or "@AAA" t
30030 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 hat serve as.**
30040 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 placeholders for
30050 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 values that are
30060 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
30070 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 lob | bound].**
30080 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 to the parameter
30090 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d s at a later tim
300a0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 e..**.** ^(This
300b0 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 routine actually
300c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 returns the ind
300d0 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 ex of the larges
300e0 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a t (rightmost).**
300f0 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 parameter. For
30100 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 all forms except
30110 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c ?NNN, this will
30120 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 correspond to t
30130 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
30140 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 unique parameter
30150 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 s. If parameter
30160 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f s of the ?NNN fo
30170 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 rm are used,.**
30180 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 there may be gap
30190 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e s in the list.)^
301a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
301b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
301c0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 lob|sqlite3_bind
301d0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
301e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
301f0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 name()], and.**
30200 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
30210 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
30220 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
30230 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
30240 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 count(sqlite3_st
30250 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
30260 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 I3REF: Name Of A
30270 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a Host Parameter.
30280 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
30290 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 e3_stmt.**.** ^T
302a0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
302b0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 parameter_name(P
302c0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 ,N) interface re
302d0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d turns.** the nam
302e0 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 e of the N-th [S
302f0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e QL parameter] in
30300 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
30310 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 tatement] P..**
30320 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 ^(SQL parameters
30330 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e of the form "?N
30340 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 NN" or ":AAA" or
30350 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 "@AAA" or "$AAA
30360 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 ".** have a name
30370 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 which is the st
30380 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 ring "?NNN" or "
30390 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 :AAA" or "@AAA"
303a0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 or "$AAA".** res
303b0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e pectively..** In
303c0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
303d0 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 e initial ":" or
303e0 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 "$" or "@" or "
303f0 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 ?".** is include
30400 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 d as part of the
30410 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 name.)^.** ^Par
30420 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 ameters of the f
30430 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 orm "?" without
30440 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 a following inte
30450 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 ger have no name
30460 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 .** and are refe
30470 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 rred to as "name
30480 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d less" or "anonym
30490 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e ous parameters".
304a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
304b0 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 t host parameter
304c0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 has an index of
304d0 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 1, not 0..**.**
304e0 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e ^If the value N
304f0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
30500 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 or if the N-th
30510 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 parameter is.**
30520 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e nameless, then N
30530 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e ULL is returned.
30540 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 ^The returned
30550 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 string is.** alw
30560 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 ays in UTF-8 enc
30570 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 oding even if th
30580 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 e named paramete
30590 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 r was.** origina
305a0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 lly specified as
305b0 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 UTF-16 in [sqli
305c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
305d0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 ,.** [sqlite3_pr
305e0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f epare16_v2()], o
305f0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
30600 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a re16_v3()]..**.*
30610 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
30620 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
30630 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
30640 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
30650 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
30660 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
30670 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
30680 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
30690 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
306a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
306b0 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ter_name(sqlite3
306c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f _stmt*, int);../
306d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
306e0 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 ndex Of A Parame
306f0 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e ter With A Given
30700 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a Name.** METHOD:
30710 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
30720 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 .** ^Return the
30730 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 index of an SQL
30740 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 parameter given
30750 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a its name. ^The.
30760 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 ** index value r
30770 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 eturned is suita
30780 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 ble for use as t
30790 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 he second.** par
307a0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
307b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c e3_bind_blob|sql
307c0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e ite3_bind()]. ^
307d0 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 A zero.** is ret
307e0 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 urned if no matc
307f0 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 hing parameter i
30800 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 s found. ^The p
30810 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 arameter.** name
30820 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 must be given i
30830 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 n UTF-8 even if
30840 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 the original sta
30850 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 tement.** was pr
30860 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d epared from UTF-
30870 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 16 text using [s
30880 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
30890 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 _v2()] or.** [sq
308a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
308b0 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 v3()]..**.** See
308c0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
308d0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
308e0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 3_bind()],.** [s
308f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
30900 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 meter_count()],
30910 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
30920 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
30930 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 ame()]..*/.int s
30940 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
30950 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 meter_index(sqli
30960 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 te3_stmt*, const
30970 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a char *zName);..
30980 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
30990 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e Reset All Bindin
309a0 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 gs On A Prepared
309b0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 Statement.** ME
309c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
309d0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 mt.**.** ^Contra
309e0 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 ry to the intuit
309f0 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 ion of many, [sq
30a00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 lite3_reset()] d
30a10 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a oes not reset.**
30a20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 the [sqlite3_bi
30a30 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e nd_blob | bindin
30a40 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 gs] on a [prepar
30a50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a ed statement]..*
30a60 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 * ^Use this rout
30a70 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c ine to reset all
30a80 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 host parameters
30a90 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 to NULL..*/.int
30aa0 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 sqlite3_clear_b
30ab0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f indings(sqlite3_
30ac0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
30ad0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
30ae0 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 Of Columns In A
30af0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 Result Set.** ME
30b00 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
30b10 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e mt.**.** ^Return
30b20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
30b30 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 olumns in the re
30b40 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 sult set returne
30b50 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 d by the.** [pre
30b60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
30b70 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 . ^If this routi
30b80 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 ne returns 0, th
30b90 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a at means the .**
30ba0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
30bb0 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f ment] returns no
30bc0 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 data (for examp
30bd0 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e le an [UPDATE]).
30be0 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 .** ^However, ju
30bf0 73 74 20 62 65 63 61 75 73 65 20 74 68 69 73 20 st because this
30c00 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
30c10 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 a positive numbe
30c20 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 r does not.** me
30c30 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d an that one or m
30c40 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61 ore rows of data
30c50 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 will be returne
30c60 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74 d. ^A SELECT st
30c70 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 atement.** will
30c80 61 6c 77 61 79 73 20 68 61 76 65 20 61 20 70 6f always have a po
30c90 73 69 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63 sitive sqlite3_c
30ca0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 olumn_count() bu
30cb0 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 t depending on t
30cc0 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 he.** WHERE clau
30cd0 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 se constraints a
30ce0 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e nd the table con
30cf0 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72 tent, it might r
30d00 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a eturn no rows..*
30d10 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
30d20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
30d30 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c nt()].*/.int sql
30d40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e ite3_column_coun
30d50 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
30d60 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
30d70 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 API3REF: Column
30d80 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c Names In A Resul
30d90 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a t Set.** METHOD:
30da0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
30db0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
30dc0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e nes return the n
30dd0 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 ame assigned to
30de0 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c a particular col
30df0 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 umn.** in the re
30e00 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 sult set of a [S
30e10 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
30e20 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
30e30 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a column_name().**
30e40 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
30e50 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
30e60 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
30e70 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a d UTF-8 string.*
30e80 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f * and sqlite3_co
30e90 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 lumn_name16() re
30ea0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
30eb0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
30ec0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 ated.** UTF-16 s
30ed0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 tring. ^The fir
30ee0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
30ef0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
30f00 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 atement].** that
30f10 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 implements the
30f20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
30f30 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 nt. ^The second
30f40 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
30f50 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 .** column numbe
30f60 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 r. ^The leftmos
30f70 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 t column is numb
30f80 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 er 0..**.** ^The
30f90 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
30fa0 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 pointer is vali
30fb0 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 d until either t
30fc0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
30fd0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 tement].** is de
30fe0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 stroyed by [sqli
30ff0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
31000 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 or until the sta
31010 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 tement is automa
31020 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 tically.** repre
31030 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 pared by the fir
31040 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 st call to [sqli
31050 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 te3_step()] for
31060 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e a particular run
31070 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 .** or until the
31080 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a next call to.**
31090 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
310a0 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 name() or sqlite
310b0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 3_column_name16(
310c0 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f ) on the same co
310d0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 lumn..**.** ^If
310e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
310f0 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 fails during th
31100 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 e processing of
31110 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a either routine.*
31120 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 * (for example d
31130 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 uring a conversi
31140 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f on from UTF-8 to
31150 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a UTF-16) then a.
31160 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 ** NULL pointer
31170 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
31180 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 ** ^The name of
31190 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 a result column
311a0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 is the value of
311b0 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 the "AS" clause
311c0 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 for.** that colu
311d0 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 mn, if there is
311e0 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 an AS clause. I
311f0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 f there is no AS
31200 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 clause.** then
31210 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
31220 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 column is unspec
31230 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 ified and may ch
31240 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 ange from.** one
31250 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
31260 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a te to the next..
31270 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
31280 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
31290 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
312a0 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 , int N);.const
312b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
312c0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 lumn_name16(sqli
312d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e te3_stmt*, int N
312e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
312f0 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 EF: Source Of Da
31300 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 ta In A Query Re
31310 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 sult.** METHOD:
31320 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
31330 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
31340 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 es provide a mea
31350 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 ns to determine
31360 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 the database, ta
31370 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c ble, and.** tabl
31380 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 e column that is
31390 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 the origin of a
313a0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 particular resu
313b0 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 lt column in.**
313c0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
313d0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 nt..** ^The name
313e0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
313f0 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c or table or col
31400 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 umn can be retur
31410 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 ned as.** either
31420 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d a UTF-8 or UTF-
31430 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 16 string. ^The
31440 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 _database_ rout
31450 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 ines return.** t
31460 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 he database name
31470 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f , the _table_ ro
31480 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
31490 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e e table name, an
314a0 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f d.** the origin_
314b0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
314c0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 the column name
314d0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e ..** ^The return
314e0 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c ed string is val
314f0 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 id until the [pr
31500 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
31510 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a ] is destroyed.*
31520 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 * using [sqlite3
31530 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 _finalize()] or
31540 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d until the statem
31550 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ent is automatic
31560 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 ally.** reprepar
31570 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
31580 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
31590 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 _step()] for a p
315a0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a articular run.**
315b0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 or until the sa
315c0 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 me information i
315d0 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 s requested.** a
315e0 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 gain in a differ
315f0 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a ent encoding..**
31600 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 .** ^The names r
31610 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 eturned are the
31620 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 original un-alia
31630 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 sed names of the
31640 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 .** database, ta
31650 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e ble, and column.
31660 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
31670 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
31680 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 ese interfaces i
31690 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 s a [prepared st
316a0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 atement]..** ^Th
316b0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 ese functions re
316c0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e turn information
316d0 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 about the Nth r
316e0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 esult column ret
316f0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 urned by.** the
31700 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 statement, where
31710 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 N is the second
31720 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
31730 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 nt..** ^The left
31740 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 -most column is
31750 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 column 0 for the
31760 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a se routines..**.
31770 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 ** ^If the Nth c
31780 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 olumn returned b
31790 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 y the statement
317a0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e is an expression
317b0 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 or.** subquery
317c0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c and is not a col
317d0 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 umn value, then
317e0 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e all of these fun
317f0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a ctions return.**
31800 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 NULL. ^These r
31810 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 outine might als
31820 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 o return NULL if
31830 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
31840 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 tion error.** oc
31850 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 curs. ^Otherwis
31860 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 e, they return t
31870 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 he name of the a
31880 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
31890 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 , table,.** or c
318a0 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 olumn that query
318b0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 result column w
318c0 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f as extracted fro
318d0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 m..**.** ^As wit
318e0 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 h all other SQLi
318f0 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 te APIs, those w
31900 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 hose names end w
31910 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a ith "16" return.
31920 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 ** UTF-16 encode
31930 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 d strings and th
31940 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e e other function
31950 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a s return UTF-8..
31960 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 **.** ^These API
31970 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c s are only avail
31980 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 able if the libr
31990 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 ary was compiled
319a0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 with the.** [SQ
319b0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 LITE_ENABLE_COLU
319c0 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 MN_METADATA] C-p
319d0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 reprocessor symb
319e0 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f ol..**.** If two
319f0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 or more threads
31a00 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 call one or mor
31a10 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 e of these routi
31a20 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 nes against the
31a30 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 same.** prepared
31a40 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 statement and c
31a50 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d olumn at the sam
31a60 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 e time then the
31a70 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 results are.** u
31a80 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
31a90 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 If two or more t
31aa0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 hreads call one
31ab0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 or more.** [sqli
31ac0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
31ad0 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d ase_name | colum
31ae0 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 n metadata inter
31af0 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 faces].** for th
31b00 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 e same [prepared
31b10 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 statement] and
31b20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a result column.**
31b30 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
31b40 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c e then the resul
31b50 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
31b60 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 ..*/.const char
31b70 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
31b80 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 database_name(sq
31b90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
31ba0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
31bb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 lite3_column_dat
31bc0 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c abase_name16(sql
31bd0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
31be0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
31bf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c ite3_column_tabl
31c00 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 e_name(sqlite3_s
31c10 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 tmt*,int);.const
31c20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
31c30 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 olumn_table_name
31c40 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
31c50 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 ,int);.const cha
31c60 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
31c70 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 n_origin_name(sq
31c80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
31c90 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
31ca0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 lite3_column_ori
31cb0 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 gin_name16(sqlit
31cc0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a e3_stmt*,int);..
31cd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
31ce0 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 Declared Datatyp
31cf0 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 e Of A Query Res
31d00 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ult.** METHOD: s
31d10 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
31d20 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 * ^(The first pa
31d30 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 rameter is a [pr
31d40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
31d50 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 ]..** If this st
31d60 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 atement is a [SE
31d70 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 LECT] statement
31d80 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 and the Nth colu
31d90 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 mn of the.** ret
31da0 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 urned result set
31db0 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 of that [SELECT
31dc0 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c ] is a table col
31dd0 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 umn (not an.** e
31de0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 xpression or sub
31df0 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 query) then the
31e00 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 declared type of
31e10 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f the table.** co
31e20 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 lumn is returned
31e30 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 .)^ ^If the Nth
31e40 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 column of the r
31e50 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a esult set is an.
31e60 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 ** expression or
31e70 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 subquery, then
31e80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
31e90 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e s returned..** ^
31ea0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
31eb0 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 ing is always UT
31ec0 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a F-8 encoded..**.
31ed0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 ** ^(For example
31ee0 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 , given the data
31ef0 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a base schema:.**.
31f00 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 ** CREATE TABLE
31f10 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a t1(c1 VARIANT);.
31f20 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f **.** and the fo
31f30 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e llowing statemen
31f40 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
31f50 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 :.**.** SELECT c
31f60 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 1 + 1, c1 FROM t
31f70 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 1;.**.** this ro
31f80 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 utine would retu
31f90 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 rn the string "V
31fa0 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 ARIANT" for the
31fb0 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a second result.**
31fc0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 column (i==1),
31fd0 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 and a NULL point
31fe0 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 er for the first
31ff0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 result column (
32000 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e i==0).)^.**.** ^
32010 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 SQLite uses dyna
32020 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 mic run-time typ
32030 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 ing. ^So just b
32040 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a ecause a column.
32050 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 ** is declared t
32060 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 o contain a part
32070 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 icular type does
32080 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 not mean that t
32090 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 he.** data store
320a0 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e d in that column
320b0 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 is of the decla
320c0 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 red type. SQLit
320d0 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 e is.** strongly
320e0 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 typed, but the
320f0 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 typing is dynami
32100 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e c not static. ^
32110 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 Type.** is assoc
32120 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 iated with indiv
32130 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f idual values, no
32140 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 t with the conta
32150 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f iners.** used to
32160 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 hold those valu
32170 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 es..*/.const cha
32180 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
32190 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 n_decltype(sqlit
321a0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 e3_stmt*,int);.c
321b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
321c0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
321d0 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d pe16(sqlite3_stm
321e0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t*,int);../*.**
321f0 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 CAPI3REF: Evalua
32200 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d te An SQL Statem
32210 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ent.** METHOD: s
32220 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
32230 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 * After a [prepa
32240 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 red statement] h
32250 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 as been prepared
32260 20 75 73 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a using any of.**
32270 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
32280 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 e_v2()], [sqlite
32290 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 3_prepare_v3()],
322a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
322b0 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 e16_v2()],.** or
322c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
322d0 65 31 36 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65 e16_v3()] or one
322e0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a of the legacy.*
322f0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 * interfaces [sq
32300 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
32310 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
32320 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 pare16()], this
32330 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 function.** must
32340 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f be called one o
32350 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 r more times to
32360 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 evaluate the sta
32370 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 tement..**.** Th
32380 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 e details of the
32390 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 behavior of the
323a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
323b0 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 interface depend
323c0 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 .** on whether t
323d0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 he statement was
323e0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 prepared using
323f0 74 68 65 20 6e 65 77 65 72 20 22 76 58 22 20 69 the newer "vX" i
32400 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71 nterfaces.** [sq
32410 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 lite3_prepare_v3
32420 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 ()], [sqlite3_pr
32430 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 epare_v2()], [sq
32440 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
32450 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 v3()],.** [sqlit
32460 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
32470 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 )] or the older
32480 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 legacy.** interf
32490 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 aces [sqlite3_pr
324a0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 epare()] and [sq
324b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
324c0 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 )]. The use of
324d0 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20 the.** new "vX"
324e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 interface is rec
324f0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 ommended for new
32500 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 applications bu
32510 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 t the legacy.**
32520 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 interface will c
32530 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 ontinue to be su
32540 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e pported..**.** ^
32550 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e In the legacy in
32560 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 terface, the ret
32570 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 urn value will b
32580 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 e either [SQLITE
32590 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 _BUSY],.** [SQLI
325a0 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 TE_DONE], [SQLIT
325b0 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f E_ROW], [SQLITE_
325c0 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 ERROR], or [SQLI
325d0 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e TE_MISUSE]..** ^
325e0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e With the "v2" in
325f0 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 terface, any of
32600 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c the other [resul
32610 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b t codes] or.** [
32620 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
32630 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 codes] might be
32640 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c returned as well
32650 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 ..**.** ^[SQLITE
32660 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 _BUSY] means tha
32670 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 t the database e
32680 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 ngine was unable
32690 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a to acquire the.
326a0 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b ** database lock
326b0 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f s it needs to do
326c0 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 its job. ^If t
326d0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
326e0 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 a [COMMIT].** or
326f0 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 occurs outside
32700 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 of an explicit t
32710 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e ransaction, then
32720 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 you can retry t
32730 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e he.** statement.
32740 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 If the stateme
32750 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d nt is not a [COM
32760 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 MIT] and occurs
32770 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 within an.** exp
32780 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f licit transactio
32790 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c n then you shoul
327a0 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 d rollback the t
327b0 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 ransaction befor
327c0 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e e.** continuing.
327d0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f .**.** ^[SQLITE_
327e0 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 DONE] means that
327f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 the statement h
32800 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 as finished exec
32810 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 uting.** success
32820 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f fully. sqlite3_
32830 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f step() should no
32840 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 t be called agai
32850 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 n on this virtua
32860 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 l.** machine wit
32870 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 hout first calli
32880 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
32890 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 t()] to reset th
328a0 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 e virtual.** mac
328b0 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 hine back to its
328c0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a initial state..
328d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 **.** ^If the SQ
328e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e L statement bein
328f0 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 g executed retur
32900 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 ns any data, the
32910 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a n [SQLITE_ROW].*
32920 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 * is returned ea
32930 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f ch time a new ro
32940 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 w of data is rea
32950 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e dy for processin
32960 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c g by the.** call
32970 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d er. The values m
32980 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 ay be accessed u
32990 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e sing the [column
329a0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e access function
329b0 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 s]..** sqlite3_s
329c0 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 tep() is called
329d0 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 again to retriev
329e0 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f e the next row o
329f0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b f data..**.** ^[
32a00 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 SQLITE_ERROR] me
32a10 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 ans that a run-t
32a20 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 ime error (such
32a30 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a as a constraint.
32a40 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 ** violation) ha
32a50 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c s occurred. sql
32a60 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 ite3_step() shou
32a70 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 ld not be called
32a80 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 again on.** the
32a90 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d VM. More inform
32aa0 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 ation may be fou
32ab0 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 nd by calling [s
32ac0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
32ad0 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c ..** ^With the l
32ae0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c egacy interface,
32af0 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 a more specific
32b00 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 error code (for
32b10 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 example,.** [SQ
32b20 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c LITE_INTERRUPT],
32b30 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
32b40 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 , [SQLITE_CORRUP
32b50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 T], and so forth
32b60 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 ).** can be obta
32b70 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 ined by calling
32b80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
32b90 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 ] on the.** [pre
32ba0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
32bb0 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 . ^In the "v2"
32bc0 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 interface,.** th
32bd0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 e more specific
32be0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 error code is re
32bf0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 turned directly
32c00 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 by sqlite3_step(
32c10 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 )..**.** [SQLITE
32c20 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 _MISUSE] means t
32c30 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 hat the this rou
32c40 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 tine was called
32c50 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e inappropriately.
32c60 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 .** Perhaps it w
32c70 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b as called on a [
32c80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
32c90 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 nt] that has.**
32ca0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 already been [sq
32cb0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c lite3_finalize |
32cc0 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f finalized] or o
32cd0 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a n one that had.*
32ce0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 * previously ret
32cf0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 urned [SQLITE_ER
32d00 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f ROR] or [SQLITE_
32d10 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f DONE]. Or it co
32d20 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 uld.** be the ca
32d30 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 se that the same
32d40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
32d50 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 tion is being us
32d60 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 ed by two or.**
32d70 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 more threads at
32d80 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 the same moment
32d90 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 in time..**.** F
32da0 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 or all versions
32db0 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 of SQLite up to
32dc0 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e and including 3.
32dd0 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6.23.1, a call t
32de0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 o.** [sqlite3_re
32df0 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 set()] was requi
32e00 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 red after sqlite
32e10 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 3_step() returne
32e20 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 d anything.** ot
32e30 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
32e40 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 _ROW] before any
32e50 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f subsequent invo
32e60 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c cation of.** sql
32e70 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 ite3_step(). Fa
32e80 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 ilure to reset t
32e90 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
32ea0 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 ement using .**
32eb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
32ec0 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 ] would result i
32ed0 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 n an [SQLITE_MIS
32ee0 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d USE] return from
32ef0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 .** sqlite3_step
32f00 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 5b (). But after [
32f10 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 version 3.6.23.1
32f20 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 ] ([dateof:3.6.2
32f30 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 3.1],.** sqlite3
32f40 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a _step() began.**
32f50 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
32f60 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 3_reset()] autom
32f70 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 atically in this
32f80 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 circumstance ra
32f90 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 ther.** than ret
32fa0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d urning [SQLITE_M
32fb0 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 ISUSE]. This is
32fc0 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 not considered
32fd0 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a a compatibility.
32fe0 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 ** break because
32ff0 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e any application
33000 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 that ever recei
33010 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 ves an SQLITE_MI
33020 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 SUSE error.** is
33030 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e broken by defin
33040 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c ition. The [SQL
33050 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 ITE_OMIT_AUTORES
33060 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 ET] compile-time
33070 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 option.** can b
33080 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 e used to restor
33090 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 e the legacy beh
330a0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e avior..**.** <b>
330b0 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 Goofy Interface
330c0 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 Alert:</b> In th
330d0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 e legacy interfa
330e0 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f ce, the sqlite3_
330f0 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c step().** API al
33100 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 ways returns a g
33110 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 eneric error cod
33120 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 e, [SQLITE_ERROR
33130 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 ], following any
33140 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 .** error other
33150 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 than [SQLITE_BUS
33160 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d Y] and [SQLITE_M
33170 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 ISUSE]. You mus
33180 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 t call.** [sqlit
33190 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b e3_reset()] or [
331a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
331b0 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ()] in order to
331c0 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a find one of the.
331d0 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 ** specific [err
331e0 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 or codes] that b
331f0 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 etter describes
33200 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 the error..** We
33210 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 admit that this
33220 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 is a goofy desi
33230 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d gn. The problem
33240 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a has been fixed.
33250 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 ** with the "v2"
33260 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 interface. If
33270 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 you prepare all
33280 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 of your SQL stat
33290 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 ements.** using
332a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
332b0 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v3()] or [sqlit
332c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
332d0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
332e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 prepare16_v2()]
332f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
33300 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 73 74 are16_v3()] inst
33310 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 ead.** of the le
33320 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 gacy [sqlite3_pr
33330 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 epare()] and [sq
33340 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
33350 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a )] interfaces,.*
33360 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 * then the more
33370 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 specific [error
33380 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 codes] are retur
33390 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 ned directly.**
333a0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 by sqlite3_step(
333b0 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 ). The use of t
333c0 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 he "vX" interfac
333d0 65 73 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 es is recommende
333e0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 d..*/.int sqlite
333f0 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 3_step(sqlite3_s
33400 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
33410 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f PI3REF: Number o
33420 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 f columns in a r
33430 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 esult set.** MET
33440 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
33450 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c t.**.** ^The sql
33460 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
33470 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 P) interface ret
33480 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
33490 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
334a0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 e.** current row
334b0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
334c0 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 et of [prepared
334d0 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a statement] P..**
334e0 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 ^If prepared st
334f0 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e atement P does n
33500 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 ot have results
33510 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a ready to return.
33520 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f ** (via calls to
33530 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
33540 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 lumn_int | sqlit
33550 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f e3_column_*()] o
33560 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 f.** interfaces)
33570 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 then sqlite3_da
33580 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 ta_count(P) retu
33590 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 rns 0..** ^The s
335a0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
335b0 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 t(P) routine als
335c0 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 o returns 0 if P
335d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
335e0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 er..** ^The sqli
335f0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 te3_data_count(P
33600 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
33610 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 s 0 if the previ
33620 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ous call to.** [
33630 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 sqlite3_step](P)
33640 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 returned [SQLIT
33650 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 E_DONE]. ^The s
33660 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
33670 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 t(P).** will ret
33680 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 urn non-zero if
33690 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
336a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 [sqlite3_step](
336b0 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b P) returned.** [
336c0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 SQLITE_ROW], exc
336d0 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 ept in the case
336e0 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 of the [PRAGMA i
336f0 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 ncremental_vacuu
33700 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 m].** where it a
33710 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 lways returns ze
33720 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 ro since each st
33730 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 ep of that multi
33740 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 -step.** pragma
33750 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e returns 0 column
33760 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a s of data..**.**
33770 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
33780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 te3_column_count
33790 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ()].*/.int sqlit
337a0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 e3_data_count(sq
337b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
337c0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
337d0 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c REF: Fundamental
337e0 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 Datatypes.** KE
337f0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 YWORDS: SQLITE_T
33800 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 EXT.**.** ^(Ever
33810 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 y value in SQLit
33820 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 e has one of fiv
33830 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 e fundamental da
33840 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c tatypes:.**.** <
33850 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 ul>.** <li> 64-b
33860 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
33870 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 r.** <li> 64-bit
33880 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 IEEE floating p
33890 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c oint number.** <
338a0 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c li> string.** <l
338b0 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 i> BLOB.** <li>
338c0 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a NULL.** </ul>)^.
338d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
338e0 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 tants are codes
338f0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 for each of thos
33900 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e e types..**.** N
33910 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c ote that the SQL
33920 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e ITE_TEXT constan
33930 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 t was also used
33940 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f in SQLite versio
33950 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d n 2.** for a com
33960 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e pletely differen
33970 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 t meaning. Soft
33980 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 ware that links
33990 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 against both.**
339a0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 SQLite version 2
339b0 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 and SQLite vers
339c0 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 ion 3 should use
339d0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e SQLITE3_TEXT, n
339e0 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 ot.** SQLITE_TEX
339f0 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 T..*/.#define SQ
33a00 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a LITE_INTEGER 1.
33a10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
33a20 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e LOAT 2.#defin
33a30 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 e SQLITE_BLOB
33a40 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
33a50 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 TE_NULL 5.#i
33a60 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 fdef SQLITE_TEXT
33a70 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f .# undef SQLITE_
33a80 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 TEXT.#else.# def
33a90 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 ine SQLITE_TEXT
33aa0 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 3.#endif.#de
33ab0 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 fine SQLITE3_TEX
33ac0 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 T 3../*.** C
33ad0 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 API3REF: Result
33ae0 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 Values From A Qu
33af0 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ery.** KEYWORDS:
33b00 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 {column access
33b10 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 functions}.** ME
33b20 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
33b30 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d mt.**.** <b>Summ
33b40 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f ary:</b>.** <blo
33b50 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 ckquote><table b
33b60 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 order=0 cellpadd
33b70 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e ing=0 cellspacin
33b80 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e g=0>.** <tr><td>
33b90 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d <b>sqlite3_colum
33ba0 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 n_blob</b><td>&r
33bb0 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73 arr;<td>BLOB res
33bc0 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c ult.** <tr><td><
33bd0 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e b>sqlite3_column
33be0 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 _double</b><td>&
33bf0 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65 rarr;<td>REAL re
33c00 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e sult.** <tr><td>
33c10 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d <b>sqlite3_colum
33c20 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 n_int</b><td>&ra
33c30 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e rr;<td>32-bit IN
33c40 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 TEGER result.**
33c50 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 <tr><td><b>sqlit
33c60 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c e3_column_int64<
33c70 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 /b><td>→<td
33c80 3e 36 34 2d 62 69 74 20 49 4e 54 45 47 45 52 20 >64-bit INTEGER
33c90 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 result.** <tr><t
33ca0 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c d><b>sqlite3_col
33cb0 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e umn_text</b><td>
33cc0 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20 →<td>UTF-8
33cd0 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c TEXT result.** <
33ce0 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 tr><td><b>sqlite
33cf0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 3_column_text16<
33d00 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 /b><td>→<td
33d10 3e 55 54 46 2d 31 36 20 54 45 58 54 20 72 65 73 >UTF-16 TEXT res
33d20 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c ult.** <tr><td><
33d30 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e b>sqlite3_column
33d40 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 _value</b><td>&r
33d50 61 72 72 3b 3c 74 64 3e 54 68 65 20 72 65 73 75 arr;<td>The resu
33d60 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 lt as an .** [sq
33d70 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72 lite3_value|unpr
33d80 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
33d90 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a value] object..*
33da0 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b * <tr><td>
33db0 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e <td> <td>&n
33dc0 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e bsp;.** <tr><td>
33dd0 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d <b>sqlite3_colum
33de0 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 n_bytes</b><td>&
33df0 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 rarr;<td>Size of
33e00 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 a BLOB.** or a
33e10 55 54 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c UTF-8 TEXT resul
33e20 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 t in bytes.** <t
33e30 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 r><td><b>sqlite3
33e40 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26 _column_bytes16&
33e50 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a nbsp; </b>.
33e60 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62 ** <td>→&nb
33e70 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a sp; <td>Siz
33e80 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54 e of UTF-16.** T
33e90 45 58 54 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 EXT in bytes.**
33ea0 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 <tr><td><b>sqlit
33eb0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f e3_column_type</
33ec0 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e b><td>→<td>
33ed0 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74 Default.** datat
33ee0 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ype of the resul
33ef0 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 t.** </table></b
33f00 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
33f10 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e <b>Details:</b>
33f20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
33f30 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e utines return in
33f40 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
33f50 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 a single column
33f60 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a of the current.*
33f70 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 * result row of
33f80 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 a query. ^In ev
33f90 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 ery case the fir
33fa0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 st argument is a
33fb0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 pointer.** to t
33fc0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
33fd0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 tement] that is
33fe0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 being evaluated
33ff0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 (the [sqlite3_st
34000 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 mt*].** that was
34010 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b returned from [
34020 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
34030 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 v2()] or one of
34040 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a its variants).**
34050 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 and the second
34060 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
34070 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c index of the col
34080 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e umn for which in
34090 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f formation.** sho
340a0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e uld be returned.
340b0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 ^The leftmost c
340c0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 olumn of the res
340d0 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 ult set has the
340e0 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 index 0..** ^The
340f0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
34100 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ns in the result
34110 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e can be determin
34120 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c ed using.** [sql
34130 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e ite3_column_coun
34140 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 t()]..**.** If t
34150 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
34160 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e does not curren
34170 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 tly point to a v
34180 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 alid row, or if
34190 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e the.** column in
341a0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 dex is out of ra
341b0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 nge, the result
341c0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
341d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
341e0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c may only be call
341f0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 ed when the most
34200 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a recent call to.
34210 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
34220 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 ()] has returned
34230 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e [SQLITE_ROW] an
34240 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 d neither.** [sq
34250 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e lite3_reset()] n
34260 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 or [sqlite3_fina
34270 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 lize()] have bee
34280 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 n called subsequ
34290 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 ently..** If any
342a0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
342b0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 es are called af
342c0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ter [sqlite3_res
342d0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c et()] or.** [sql
342e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
342f0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 or after [sqlit
34300 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 e3_step()] has r
34310 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 eturned.** somet
34320 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 hing other than
34330 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 [SQLITE_ROW], th
34340 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
34350 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b defined..** If [
34360 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
34370 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 or [sqlite3_rese
34380 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 t()] or [sqlite3
34390 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 _finalize()].**
343a0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 are called from
343b0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 a different thre
343c0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 ad while any of
343d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a these routines.*
343e0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 * are pending, t
343f0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 hen the results
34400 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
34410 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 73 *.** The first s
34420 69 78 20 69 6e 74 65 72 66 61 63 65 73 20 28 5f ix interfaces (_
34430 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f blob, _double, _
34440 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65 int, _int64, _te
34450 78 74 2c 20 61 6e 64 20 5f 74 65 78 74 31 36 29 xt, and _text16)
34460 0a 2a 2a 20 65 61 63 68 20 72 65 74 75 72 6e 20 .** each return
34470 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 72 the value of a r
34480 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 esult column in
34490 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61 20 a specific data
344a0 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74 format. If.** t
344b0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e he result column
344c0 20 69 73 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c is not initiall
344d0 79 20 69 6e 20 74 68 65 20 72 65 71 75 65 73 74 y in the request
344e0 65 64 20 66 6f 72 6d 61 74 20 28 66 6f 72 20 65 ed format (for e
344f0 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 xample,.** if th
34500 65 20 71 75 65 72 79 20 72 65 74 75 72 6e 73 20 e query returns
34510 61 6e 20 69 6e 74 65 67 65 72 20 62 75 74 20 74 an integer but t
34520 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
34530 6e 5f 74 65 78 74 28 29 20 69 6e 74 65 72 66 61 n_text() interfa
34540 63 65 0a 2a 2a 20 69 73 20 75 73 65 64 20 74 6f ce.** is used to
34550 20 65 78 74 72 61 63 74 20 74 68 65 20 76 61 6c extract the val
34560 75 65 29 20 74 68 65 6e 20 61 6e 20 61 75 74 6f ue) then an auto
34570 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65 matic type conve
34580 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d rsion is perform
34590 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
345a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
345b0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 pe() routine ret
345c0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c urns the.** [SQL
345d0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 ITE_INTEGER | da
345e0 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 tatype code] for
345f0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 the initial dat
34600 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 a type.** of the
34610 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 result column.
34620 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 ^The returned v
34630 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b alue is one of [
34640 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c SQLITE_INTEGER],
34650 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 .** [SQLITE_FLOA
34660 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 T], [SQLITE_TEXT
34670 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d ], [SQLITE_BLOB]
34680 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c , or [SQLITE_NUL
34690 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 L]..** The retur
346a0 6e 20 76 61 6c 75 65 20 6f 66 20 73 71 6c 69 74 n value of sqlit
346b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
346c0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
346d0 64 65 63 69 64 65 20 77 68 69 63 68 0a 2a 2a 20 decide which.**
346e0 6f 66 20 74 68 65 20 66 69 72 73 74 20 73 69 78 of the first six
346f0 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c interface shoul
34700 64 20 62 65 20 75 73 65 64 20 74 6f 20 65 78 74 d be used to ext
34710 72 61 63 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20 ract the column
34720 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61 value..** The va
34730 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
34740 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
34750 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 ype() is only me
34760 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a aningful if no.*
34770 2a 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65 * automatic type
34780 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 conversions hav
34790 65 20 6f 63 63 75 72 72 65 64 20 66 6f 72 20 74 e occurred for t
347a0 68 65 20 76 61 6c 75 65 20 69 6e 20 71 75 65 73 he value in ques
347b0 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72 tion. .** After
347c0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 a type conversi
347d0 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c 74 20 6f on, the result o
347e0 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 f calling sqlite
347f0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 3_column_type().
34800 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2c ** is undefined,
34810 20 74 68 6f 75 67 68 20 68 61 72 6d 6c 65 73 73 though harmless
34820 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 . Future.** ver
34830 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
34840 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 may change the b
34850 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 ehavior of sqlit
34860 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
34870 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 .** following a
34880 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e type conversion.
34890 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 .**.** If the re
348a0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f sult is a BLOB o
348b0 72 20 61 20 54 45 58 54 20 73 74 72 69 6e 67 2c r a TEXT string,
348c0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 then the sqlite
348d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
348e0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 .** or sqlite3_c
348f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
34900 69 6e 74 65 72 66 61 63 65 73 20 63 61 6e 20 62 interfaces can b
34910 65 20 75 73 65 64 20 74 6f 20 64 65 74 65 72 6d e used to determ
34920 69 6e 65 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 ine the size.**
34930 6f 66 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 of that BLOB or
34940 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 string..**.** ^I
34950 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
34960 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 a BLOB or UTF-8
34970 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 string then the
34980 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
34990 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e ytes().** routin
349a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
349b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
349c0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 that BLOB or st
349d0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ring..** ^If the
349e0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 result is a UTF
349f0 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e -16 string, then
34a00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
34a10 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 bytes() converts
34a20 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 .** the string t
34a30 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e o UTF-8 and then
34a40 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
34a50 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a ber of bytes..**
34a60 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
34a70 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c is a numeric val
34a80 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ue then sqlite3_
34a90 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 column_bytes() u
34aa0 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ses.** [sqlite3_
34ab0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 snprintf()] to c
34ac0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 onvert that valu
34ad0 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 e to a UTF-8 str
34ae0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a ing and returns.
34af0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
34b00 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 bytes in that s
34b10 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 tring..** ^If th
34b20 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c e result is NULL
34b30 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
34b40 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 olumn_bytes() re
34b50 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a turns zero..**.*
34b60 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
34b70 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 is a BLOB or UT
34b80 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e F-16 string then
34b90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c the sqlite3_col
34ba0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a umn_bytes16().**
34bb0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
34bc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
34bd0 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f ytes in that BLO
34be0 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 B or string..**
34bf0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
34c00 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 s a UTF-8 string
34c10 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
34c20 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
34c30 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 converts.** the
34c40 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 string to UTF-16
34c50 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e and then return
34c60 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
34c70 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 bytes..** ^If th
34c80 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 e result is a nu
34c90 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e meric value then
34ca0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
34cb0 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a bytes16() uses.*
34cc0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 * [sqlite3_snpri
34cd0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 ntf()] to conver
34ce0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 t that value to
34cf0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 a UTF-16 string
34d00 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 and returns.** t
34d10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
34d20 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e es in that strin
34d30 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 g..** ^If the re
34d40 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 sult is NULL, th
34d50 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
34d60 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 n_bytes16() retu
34d70 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 rns zero..**.**
34d80 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 ^The values retu
34d90 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
34da0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d _column_bytes()]
34db0 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 and .** [sqlite
34dc0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
34dd0 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 ()] do not inclu
34de0 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d de the zero term
34df0 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 inators at the e
34e00 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 nd.** of the str
34e10 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 ing. ^For clari
34e20 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 ty: the values r
34e30 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
34e40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
34e50 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 tes()] and [sqli
34e60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
34e70 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 16()] are the nu
34e80 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 mber of.** bytes
34e90 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 in the string,
34ea0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f not the number o
34eb0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a f characters..**
34ec0 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 .** ^Strings ret
34ed0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
34ee0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 _column_text() a
34ef0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
34f00 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 n_text16(),.** e
34f10 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 ven empty string
34f20 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 s, are always ze
34f30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 ro-terminated.
34f40 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 ^The return.** v
34f50 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
34f60 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 3_column_blob()
34f70 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 for a zero-lengt
34f80 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c h BLOB is a NULL
34f90 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
34fa0 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 <b>Warning:</b>
34fb0 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 ^The object retu
34fc0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
34fd0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
34fe0 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f is an.** [unpro
34ff0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
35000 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 alue] object. I
35010 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 n a multithreade
35020 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a d environment,.*
35030 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 * an unprotected
35040 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
35050 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 bject may only b
35060 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 e used safely wi
35070 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 th.** [sqlite3_b
35080 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 ind_value()] and
35090 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
350a0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 _value()]..** If
350b0 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 the [unprotecte
350c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
350d0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 object returned
350e0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f by.** [sqlite3_
350f0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 column_value()]
35100 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f is used in any o
35110 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 ther way, includ
35120 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 ing calls.** to
35130 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 routines like [s
35140 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 qlite3_value_int
35150 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 ()], [sqlite3_va
35160 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 lue_text()],.**
35170 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 or [sqlite3_valu
35180 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 e_bytes()], the
35190 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 behavior is not
351a0 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48 threadsafe..** H
351b0 65 6e 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 ence, the sqlite
351c0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 3_column_value()
351d0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 interface.** is
351e0 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 normally only u
351f0 73 65 66 75 6c 20 77 69 74 68 69 6e 20 74 68 65 seful within the
35200 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
35210 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74 of .** [applicat
35220 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
35230 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 functions] or [v
35240 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20 irtual tables],
35250 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f not within.** to
35260 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69 63 61 74 p-level applicat
35270 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 ion code..**.**
35280 54 68 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e The these routin
35290 65 73 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 es may attempt t
352a0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 64 61 o convert the da
352b0 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 65 tatype of the re
352c0 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 sult..** ^For ex
352d0 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e ample, if the in
352e0 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 ternal represent
352f0 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 ation is FLOAT a
35300 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 nd a text result
35310 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 .** is requested
35320 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 , [sqlite3_snpri
35330 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 ntf()] is used i
35340 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 nternally to per
35350 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 form the.** conv
35360 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 ersion automatic
35370 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c ally. ^(The fol
35380 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 lowing table det
35390 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 ails the convers
353a0 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ions.** that are
353b0 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 applied:.**.**
353c0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 <blockquote>.**
353d0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 <table border="1
353e0 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 ">.** <tr><th> I
353f0 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 nternal<br>Type
35400 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 <th> Requested<b
35410 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e r>Type <th> Con
35420 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 version.**.** <t
35430 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
35440 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
35450 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a td> Result is 0.
35460 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
35470 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 L <td> FLOAT
35480 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 <td> Result
35490 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 is 0.0.** <tr><t
354a0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
354b0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 TEXT <td>
354c0 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c Result is a NULL
354d0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e pointer.** <tr>
354e0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
354f0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
35500 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 > Result is a NU
35510 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 LL pointer.** <t
35520 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 r><td> INTEGER
35530 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
35540 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d td> Convert from
35550 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 integer to floa
35560 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e t.** <tr><td> IN
35570 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 TEGER <td> TE
35580 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 XT <td> ASCII
35590 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
355a0 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 e integer.** <tr
355b0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c ><td> INTEGER <
355c0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
355d0 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 d> Same as INTEG
355e0 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e ER->TEXT.** <tr>
355f0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 <td> FLOAT <t
35600 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
35610 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 > [CAST] to INTE
35620 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 GER.** <tr><td>
35630 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 FLOAT <td>
35640 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 TEXT <td> ASC
35650 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 II rendering of
35660 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 the float.** <tr
35670 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c ><td> FLOAT <
35680 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
35690 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f d> [CAST] to BLO
356a0 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 B.** <tr><td> T
356b0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 EXT <td> INTE
356c0 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 GER <td> [CAST
356d0 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 ] to INTEGER.**
356e0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 <tr><td> TEXT
356f0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
35700 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 <td> [CAST] to
35710 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e REAL.** <tr><td>
35720 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 TEXT <td>
35730 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f BLOB <td> No
35740 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c change.** <tr><
35750 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 td> BLOB <td
35760 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e > INTEGER <td>
35770 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 [CAST] to INTEG
35780 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ER.** <tr><td>
35790 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c BLOB <td> FL
357a0 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 OAT <td> [CAS
357b0 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 T] to REAL.** <t
357c0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 r><td> BLOB
357d0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
357e0 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 td> Add a zero t
357f0 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 erminator if nee
35800 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a ded.** </table>.
35810 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e ** </blockquote>
35820 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 )^.**.** Note th
35830 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e at when type con
35840 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 versions occur,
35850 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
35860 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 d by prior.** ca
35870 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
35880 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 olumn_blob(), sq
35890 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
358a0 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 t(), and/or.** s
358b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
358c0 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e xt16() may be in
358d0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 validated..** Ty
358e0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 pe conversions a
358f0 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c nd pointer inval
35900 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f idations might o
35910 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 ccur.** in the f
35920 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a ollowing cases:.
35930 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
35940 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 i> The initial c
35950 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 ontent is a BLOB
35960 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
35970 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a umn_text() or.**
35980 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f sqlite3_co
35990 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 lumn_text16() is
359a0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f called. A zero
359b0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 -terminator migh
359c0 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 t.** need t
359d0 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 o be added to th
359e0 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a e string.</li>.*
359f0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 * <li> The initi
35a00 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 al content is UT
35a10 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c F-8 text and sql
35a20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
35a30 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 s16() or.**
35a40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
35a50 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c text16() is call
35a60 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 ed. The content
35a70 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 must be convert
35a80 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 ed.** to UT
35a90 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c F-16.</li>.** <l
35aa0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 i> The initial c
35ab0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 ontent is UTF-16
35ac0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 text and sqlite
35ad0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
35ae0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 or.** sqli
35af0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
35b00 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 ) is called. Th
35b10 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 e content must b
35b20 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 e converted.**
35b30 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c to UTF-8.</l
35b40 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a i>.** </ul>.**.*
35b50 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 * ^Conversions b
35b60 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 etween UTF-16be
35b70 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 and UTF-16le are
35b80 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 always done in
35b90 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 place and do.**
35ba0 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 not invalidate a
35bb0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 prior pointer,
35bc0 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 though of course
35bd0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
35be0 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 the buffer.** th
35bf0 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 at the prior poi
35c00 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 nter references
35c10 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d will have been m
35c20 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 odified. Other
35c30 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 kinds.** of conv
35c40 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 ersion are done
35c50 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 in place when it
35c60 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 is possible, bu
35c70 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 t sometimes they
35c80 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 .** are not poss
35c90 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 ible and in thos
35ca0 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f e cases prior po
35cb0 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c inters are inval
35cc0 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 idated..**.** Th
35cd0 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 e safest policy
35ce0 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 is to invoke the
35cf0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 se routines.** i
35d00 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c n one of the fol
35d10 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a lowing ways:.**.
35d20 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e ** <ul>.** <li>
35d30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
35d40 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 ext() followed b
35d50 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
35d60 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a _bytes()</li>.**
35d70 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f <li>sqlite3_co
35d80 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c lumn_blob() foll
35d90 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f owed by sqlite3_
35da0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f column_bytes()</
35db0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 li>.** <li>sqli
35dc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
35dd0 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6() followed by
35de0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
35df0 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a ytes16()</li>.**
35e00 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 </ul>.**.** In
35e10 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 other words, you
35e20 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c should call sql
35e30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
35e40 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 (),.** sqlite3_c
35e50 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 olumn_blob(), or
35e60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
35e70 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 text16() first t
35e80 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 o force the resu
35e90 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 lt.** into the d
35ea0 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 esired format, t
35eb0 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 hen invoke sqlit
35ec0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
35ed0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
35ee0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
35ef0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a to find the siz
35f00 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e e of the result.
35f10 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c Do not mix cal
35f20 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 ls.** to sqlite3
35f30 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f _column_text() o
35f40 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
35f50 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c _blob() with cal
35f60 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
35f70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
35f80 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 ), and do not mi
35f90 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 x calls to sqlit
35fa0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
35fb0 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 ().** with calls
35fc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
35fd0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a mn_bytes()..**.*
35fe0 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 * ^The pointers
35ff0 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c returned are val
36000 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 id until a type
36010 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 conversion occur
36020 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 s as.** describe
36030 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 d above, or unti
36040 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 l [sqlite3_step(
36050 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
36060 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
36070 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
36080 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e )] is called. ^
36090 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 The memory space
360a0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 used to hold st
360b0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f rings.** and BLO
360c0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f Bs is freed auto
360d0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e matically. Do n
360e0 6f 74 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e ot pass the poin
360f0 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a ters returned.**
36100 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 from [sqlite3_c
36110 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b olumn_blob()], [
36120 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
36130 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 ext()], etc. int
36140 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 o.** [sqlite3_fr
36150 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 ee()]..**.** ^(I
36160 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
36170 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 ation error occu
36180 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 rs during the ev
36190 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a aluation of any.
361a0 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ** of these rout
361b0 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 ines, a default
361c0 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 value is returne
361d0 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 d. The default
361e0 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 value.** is eith
361f0 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 er the integer 0
36200 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 , the floating p
36210 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c oint number 0.0,
36220 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f or a NULL.** po
36230 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 inter. Subseque
36240 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c nt calls to [sql
36250 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 ite3_errcode()]
36260 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b will return.** [
36270 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e SQLITE_NOMEM].)^
36280 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a .*/.const void *
36290 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
362a0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
362b0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f *, int iCol);.do
362c0 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c uble sqlite3_col
362d0 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 umn_double(sqlit
362e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
362f0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ol);.int sqlite3
36300 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 _column_int(sqli
36310 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
36320 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e Col);.sqlite3_in
36330 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 t64 sqlite3_colu
36340 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 mn_int64(sqlite3
36350 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
36360 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 );.const unsigne
36370 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f d char *sqlite3_
36380 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 column_text(sqli
36390 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
363a0 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 Col);.const void
363b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
363c0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f _text16(sqlite3_
363d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
363e0 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 ;.sqlite3_value
363f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
36400 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 value(sqlite3_st
36410 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
36420 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
36430 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 mn_bytes(sqlite3
36440 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
36450 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
36460 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 olumn_bytes16(sq
36470 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
36480 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 iCol);.int sqli
36490 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
364a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
364b0 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a nt iCol);../*.**
364c0 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 CAPI3REF: Destr
364d0 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 oy A Prepared St
364e0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a atement Object.*
364f0 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 * DESTRUCTOR: sq
36500 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
36510 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 ^The sqlite3_fi
36520 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f nalize() functio
36530 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 n is called to d
36540 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 elete a [prepare
36550 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
36560 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ^If the most re
36570 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 cent evaluation
36580 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 of the statement
36590 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 encountered no
365a0 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 errors.** or if
365b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
365c0 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c never been eval
365d0 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 uated, then sqli
365e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 te3_finalize() r
365f0 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 eturns.** SQLITE
36600 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f _OK. ^If the mo
36610 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 st recent evalua
36620 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e tion of statemen
36630 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e t S failed, then
36640 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 .** sqlite3_fina
36650 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 lize(S) returns
36660 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 the appropriate
36670 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a [error code] or.
36680 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 ** [extended err
36690 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 or code]..**.**
366a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e ^The sqlite3_fin
366b0 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 alize(S) routine
366c0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 can be called a
366d0 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 t any point duri
366e0 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 ng.** the life c
366f0 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 ycle of [prepare
36700 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a d statement] S:.
36710 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d ** before statem
36720 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76 ent S is ever ev
36730 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a aluated, after.*
36740 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 * one or more ca
36750 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
36760 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 reset()], or aft
36770 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 er any call.** t
36780 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
36790 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 )] regardless of
367a0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
367b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 the statement ha
367c0 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 s.** completed e
367d0 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 xecution..**.**
367e0 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 ^Invoking sqlite
367f0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 3_finalize() on
36800 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
36810 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d s a harmless no-
36820 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 op..**.** The ap
36830 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 plication must f
36840 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 inalize every [p
36850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
36860 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 t] in order to a
36870 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 void.** resource
36880 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 leaks. It is a
36890 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 grievous error
368a0 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 for the applicat
368b0 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 ion to try to us
368c0 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 e.** a prepared
368d0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 statement after
368e0 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 it has been fina
368f0 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 lized. Any use
36900 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a of a prepared.**
36910 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 statement after
36920 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e it has been fin
36930 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c alized can resul
36940 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 t in undefined a
36950 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c nd.** undesirabl
36960 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 e behavior such
36970 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 as segfaults and
36980 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e heap corruption
36990 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
369a0 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 _finalize(sqlite
369b0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
369c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
369d0 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 Reset A Prepare
369e0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 d Statement Obje
369f0 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ct.** METHOD: sq
36a00 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
36a10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
36a20 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 et() function is
36a30 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 called to reset
36a40 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
36a50 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 tement].** objec
36a60 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e t back to its in
36a70 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 itial state, rea
36a80 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 dy to be re-exec
36a90 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 uted..** ^Any SQ
36aa0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 L statement vari
36ab0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 ables that had v
36ac0 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 alues bound to t
36ad0 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 hem using.** the
36ae0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
36af0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 lob | sqlite3_bi
36b00 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 nd_*() API] reta
36b10 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e in their values.
36b20 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 .** Use [sqlite3
36b30 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 _clear_bindings(
36b40 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 )] to reset the
36b50 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 bindings..**.**
36b60 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 ^The [sqlite3_re
36b70 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 set(S)] interfac
36b80 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 e resets the [pr
36b90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
36ba0 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 ] S.** back to t
36bb0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
36bc0 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a its program..**.
36bd0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 ** ^If the most
36be0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b recent call to [
36bf0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
36c00 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 for the.** [pre
36c10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
36c20 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c S returned [SQL
36c30 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c ITE_ROW] or [SQL
36c40 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 ITE_DONE],.** or
36c50 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 if [sqlite3_ste
36c60 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 p(S)] has never
36c70 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c before been call
36c80 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e ed on S,.** then
36c90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
36ca0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c S)] returns [SQL
36cb0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e ITE_OK]..**.** ^
36cc0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
36cd0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
36ce0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 te3_step(S)] for
36cf0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
36d00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 d statement] S i
36d10 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f ndicated an erro
36d20 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 r, then.** [sqli
36d30 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 te3_reset(S)] re
36d40 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 turns an appropr
36d50 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 iate [error code
36d60 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 ]..**.** ^The [s
36d70 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
36d80 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 interface does
36d90 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 not change the v
36da0 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 alues.** of any
36db0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
36dc0 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 ob|bindings] on
36dd0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
36de0 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 atement] S..*/.i
36df0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 nt sqlite3_reset
36e00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
36e10 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
36e20 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f PI3REF: Create O
36e30 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 r Redefine SQL F
36e40 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 unctions.** KEYW
36e50 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 ORDS: {function
36e60 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 creation routine
36e70 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 s}.** KEYWORDS:
36e80 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 {application-def
36e90 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
36ea0 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 n}.** KEYWORDS:
36eb0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 {application-def
36ec0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
36ed0 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ns}.** METHOD: s
36ee0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
36ef0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 ese functions (c
36f00 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 ollectively know
36f10 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 n as "function c
36f20 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 reation routines
36f30 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 ").** are used t
36f40 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 o add SQL functi
36f50 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
36f60 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 s or to redefine
36f70 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a the behavior.**
36f80 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c of existing SQL
36f90 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 functions or ag
36fa0 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f gregates. The o
36fb0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 nly differences
36fc0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 between.** these
36fd0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 routines are th
36fe0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 e text encoding
36ff0 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 expected for.**
37000 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
37010 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f eter (the name o
37020 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 f the function b
37030 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a eing created).**
37040 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 and the presenc
37050 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 e or absence of
37060 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c a destructor cal
37070 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 lback for.** the
37080 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
37090 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a a pointer..**.**
370a0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 ^The first para
370b0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 meter is the [da
370c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
370d0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 n] to which the
370e0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 SQL.** function
370f0 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 is to be added.
37100 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 ^If an applicat
37110 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 ion uses more th
37120 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a an one database.
37130 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 ** connection th
37140 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 en application-d
37150 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
37160 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 ions must be add
37170 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 ed.** to each da
37180 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
37190 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a n separately..**
371a0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 .** ^The second
371b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
371c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c name of the SQL
371d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
371e0 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 created or.** re
371f0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c defined. ^The l
37200 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d ength of the nam
37210 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 e is limited to
37220 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 255 bytes in a U
37230 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e TF-8.** represen
37240 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 tation, exclusiv
37250 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 e of the zero-te
37260 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 rminator. ^Note
37270 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a that the name.*
37280 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 * length limit i
37290 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 s in UTF-8 bytes
372a0 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 , not characters
372b0 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 nor UTF-16 byte
372c0 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 s. .** ^Any att
372d0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 empt to create a
372e0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
372f0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 longer name.**
37300 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b will result in [
37310 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 SQLITE_MISUSE] b
37320 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a eing returned..*
37330 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 *.** ^The third
37340 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 parameter (nArg)
37350 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 .** is the numbe
37360 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 r of arguments t
37370 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 hat the SQL func
37380 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
37390 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 gate takes. ^If
373a0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 this parameter i
373b0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 s -1, then the S
373c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a QL function or.*
373d0 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 * aggregate may
373e0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 take any number
373f0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 of arguments bet
37400 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c ween 0 and the l
37410 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b imit.** set by [
37420 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b sqlite3_limit]([
37430 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
37440 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 CTION_ARG]). If
37450 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 the third.** pa
37460 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 rameter is less
37470 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 than -1 or great
37480 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e er than 127 then
37490 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
374a0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a .** undefined..*
374b0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 *.** ^The fourth
374c0 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 parameter, eTex
374d0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 tRep, specifies
374e0 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f what.** [SQLITE_
374f0 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f UTF8 | text enco
37500 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 ding] this SQL f
37510 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 unction prefers
37520 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d for.** its param
37530 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c eters. The appl
37540 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 ication should s
37550 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 et this paramete
37560 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f r to.** [SQLITE_
37570 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 UTF16LE] if the
37580 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
37590 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 ntation invokes
375a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
375b0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f ue_text16le()] o
375c0 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b n an input, or [
375d0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 SQLITE_UTF16BE]
375e0 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d if the.** implem
375f0 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 entation invokes
37600 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
37610 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 text16be()] on a
37620 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b n input, or.** [
37630 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 SQLITE_UTF16] if
37640 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
37650 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 text16()] is use
37660 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 d, or [SQLITE_UT
37670 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 F8].** otherwise
37680 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c . ^The same SQL
37690 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 function may be
376a0 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 registered mult
376b0 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 iple times using
376c0 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 .** different pr
376d0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 eferred text enc
376e0 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 odings, with dif
376f0 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 ferent implement
37700 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 ations for.** ea
37710 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 ch encoding..**
37720 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 ^When multiple i
37730 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
37740 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 f the same funct
37750 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c ion are availabl
37760 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c e, SQLite.** wil
37770 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 l pick the one t
37780 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 hat involves the
37790 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 least amount of
377a0 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e data conversion
377b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
377c0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 rth parameter ma
377d0 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 y optionally be
377e0 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 ORed with [SQLIT
377f0 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d E_DETERMINISTIC]
37800 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 .** to signal th
37810 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 at the function
37820 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 will always retu
37830 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 rn the same resu
37840 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 lt given.** the
37850 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 same inputs with
37860 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 in a single SQL
37870 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 statement. Most
37880 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 SQL functions a
37890 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 re.** determinis
378a0 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d tic. The built-
378b0 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 in [random()] SQ
378c0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e L function is an
378d0 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a example of a.**
378e0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 function that i
378f0 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 s not determinis
37900 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 tic. The SQLite
37910 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 query planner i
37920 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 s able to.** per
37930 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 form additional
37940 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e optimizations on
37950 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 deterministic f
37960 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 unctions, so use
37970 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 .** of the [SQLI
37980 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 TE_DETERMINISTIC
37990 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d ] flag is recomm
379a0 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 ended where poss
379b0 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ible..**.** ^(Th
379c0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 e fifth paramete
379d0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 r is an arbitrar
379e0 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 y pointer. The
379f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
37a00 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f f the.** functio
37a10 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 n can gain acces
37a20 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 s to this pointe
37a30 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 r using [sqlite3
37a40 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e _user_data()].)^
37a50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 .**.** ^The sixt
37a60 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 h, seventh and e
37a70 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 ighth parameters
37a80 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 , xFunc, xStep a
37a90 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a nd xFinal, are.*
37aa0 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d * pointers to C-
37ab0 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f language functio
37ac0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e ns that implemen
37ad0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 t the SQL functi
37ae0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 on or.** aggrega
37af0 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 te. ^A scalar SQ
37b00 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 L function requi
37b10 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 res an implement
37b20 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 ation of the xFu
37b30 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f nc.** callback o
37b40 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 nly; NULL pointe
37b50 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 rs must be passe
37b60 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 d as the xStep a
37b70 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 nd xFinal.** par
37b80 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 ameters. ^An agg
37b90 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 regate SQL funct
37ba0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 ion requires an
37bb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
37bc0 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 f xStep.** and x
37bd0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 Final and NULL p
37be0 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 ointer must be p
37bf0 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e assed for xFunc.
37c00 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 ^To delete an e
37c10 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 xisting.** SQL f
37c20 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 unction or aggre
37c30 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 gate, pass NULL
37c40 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c pointers for all
37c50 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a three function.
37c60 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a ** callbacks..**
37c70 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e .** ^(If the nin
37c80 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
37c90 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
37ca0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 unction_v2() is
37cb0 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 not NULL,.** the
37cc0 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 n it is destruct
37cd0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 or for the appli
37ce0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
37cf0 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 ter. .** The des
37d00 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b tructor is invok
37d10 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 ed when the func
37d20 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c tion is deleted,
37d30 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 either by being
37d40 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f .** overloaded o
37d50 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 r when the datab
37d60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 ase connection c
37d70 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 loses.)^.** ^The
37d80 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 destructor is a
37d90 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 lso invoked if t
37da0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 he call to.** sq
37db0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
37dc0 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 ction_v2() fails
37dd0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 ..** ^When the d
37de0 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 estructor callba
37df0 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 ck of the tenth
37e00 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 parameter is inv
37e10 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 oked, it.** is p
37e20 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 assed a single a
37e30 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
37e40 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 a copy of the a
37e50 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 pplication data
37e60 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 .** pointer whic
37e70 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 h was the fifth
37e80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
37e90 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
37ea0 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a tion_v2()..**.**
37eb0 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 ^It is permitte
37ec0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 d to register mu
37ed0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 ltiple implement
37ee0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
37ef0 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 me.** functions
37f00 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 with the same na
37f10 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 me but with eith
37f20 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d er differing num
37f30 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d bers of.** argum
37f40 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e ents or differin
37f50 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 g preferred text
37f60 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 encodings. ^SQ
37f70 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a Lite will use.**
37f80 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
37f90 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c ion that most cl
37fa0 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 osely matches th
37fb0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 e way in which t
37fc0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 he.** SQL functi
37fd0 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 on is used. ^A
37fe0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
37ff0 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e ntation with a n
38000 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e on-negative.** n
38010 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 Arg parameter is
38020 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 a better match
38030 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 than a function
38040 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
38050 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 ith.** a negativ
38060 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 e nArg. ^A func
38070 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 tion where the p
38080 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
38090 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 coding.** matche
380a0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 s the database e
380b0 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 ncoding is a bet
380c0 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 ter.** match tha
380d0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 n a function whe
380e0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 re the encoding
380f0 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a is different. .
38100 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 ** ^A function w
38110 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e here the encodin
38120 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 g difference is
38130 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 between UTF16le
38140 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 and UTF16be.** i
38150 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 s a closer match
38160 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e than a function
38170 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 where the encod
38180 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 ing difference i
38190 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 s.** between UTF
381a0 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 8 and UTF16..**.
381b0 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e ** ^Built-in fun
381c0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 ctions may be ov
381d0 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 erloaded by new
381e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
381f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a ned functions..*
38200 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 *.** ^An applica
38210 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
38220 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 ction is permitt
38230 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 ed to call other
38240 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 .** SQLite inter
38250 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c faces. However,
38260 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 such calls must
38270 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 not.** close th
38280 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
38290 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 ction nor finali
382a0 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 ze or reset the
382b0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
382c0 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 ement in which t
382d0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 he function is r
382e0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 unning..*/.int s
382f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
38300 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 nction(. sqlite
38310 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 3 *db,. const c
38320 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 har *zFunctionNa
38330 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a me,. int nArg,.
38340 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a int eTextRep,.
38350 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 void *pApp,.
38360 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 void (*xFunc)(sq
38370 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
38380 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
38390 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 **),. void (*xS
383a0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e tep)(sqlite3_con
383b0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
383c0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
383d0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c id (*xFinal)(sql
383e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 ite3_context*).)
383f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 ;.int sqlite3_cr
38400 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
38410 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a . sqlite3 *db,.
38420 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 const void *zF
38430 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 unctionName,. i
38440 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 nt nArg,. int e
38450 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 TextRep,. void
38460 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a *pApp,. void (*
38470 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 xFunc)(sqlite3_c
38480 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
38490 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
384a0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 void (*xStep)(sq
384b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
384c0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
384d0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 **),. void (*xF
384e0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f inal)(sqlite3_co
384f0 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 ntext*).);.int s
38500 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
38510 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c nction_v2(. sql
38520 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
38530 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f t char *zFunctio
38540 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
38550 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
38560 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
38570 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
38580 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
38590 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
385a0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
385b0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
385c0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
385d0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
385e0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
385f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
38600 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 ),. void(*xDest
38610 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a roy)(void*).);..
38620 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
38630 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a Text Encodings.*
38640 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
38650 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 ant define integ
38660 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 er codes that re
38670 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 present the vari
38680 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f ous.** text enco
38690 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 dings supported
386a0 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 by SQLite..*/.#d
386b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
386c0 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20 20 8 1
386d0 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 /* IMP: R-37514
386e0 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e -35566 */.#defin
386f0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 e SQLITE_UTF16LE
38700 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 2 /*
38710 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 IMP: R-03371-376
38720 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 37 */.#define SQ
38730 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 LITE_UTF16BE
38740 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 3 /* IMP:
38750 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a R-51971-34154 *
38760 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
38770 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 _UTF16
38780 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 4 /* Use nati
38790 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f ve byte order */
387a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
387b0 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 ANY 5
387c0 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 /* Deprecate
387d0 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
387e0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45