0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 ms copyright to
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a . In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d sing:.**.** M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 nd not evil..**
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 May you find
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 forgiveness for
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 give others..**
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aking more than
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a you give..**.***
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 2a ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 rograms. If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 s file, then it
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 ite, is subject
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 erimental". Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 to SQLite. We
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 74 6f e changes .** to
0390: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e experimental in
03a0: 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 terfaces but res
03b0: 65 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e erve to make min
03c0: 6f 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a or changes if.**
03d0: 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d experience from
03e0: 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c use "in the wil
03f0: 64 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 d" suggest such
0400: 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 changes are prud
0410: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f ent..**.** The o
0420: 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 fficial C-langua
0430: 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 ge API documenta
0440: 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 tion for SQLite
0450: 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 is derived.** fr
0460: 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 om comments in t
0470: 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 his file. This
0480: 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 file is the auth
0490: 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 oritative source
04a0: 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 .** on how SQLit
04b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 e interfaces are
04c0: 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 suppose to oper
04d0: 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e ate..**.** The n
04e0: 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 ame of this file
04f0: 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 under configura
0500: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 tion management
0510: 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 is "sqlite.h.in"
0520: 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c ..** The makefil
0530: 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e e makes some min
0540: 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 or changes to th
0550: 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 is file (such as
0560: 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 inserting.** th
0570: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 e version number
0580: 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 ) and changes it
0590: 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 s name to "sqlit
05a0: 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 e3.h" as.** part
05b0: 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 of the build pr
05c0: 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 ocess..**.** @(#
05d0: 29 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e ) $Id: sqlite.h.
05e0: 69 6e 2c 76 20 31 2e 32 34 33 20 32 30 30 37 2f in,v 1.243 2007/
05f0: 30 38 2f 32 37 20 31 37 3a 32 37 3a 34 39 20 64 08/27 17:27:49 d
0600: 61 6e 69 65 6c 6b 31 39 37 37 20 45 78 70 20 24 anielk1977 Exp $
0610: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c .*/.#ifndef _SQL
0620: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 ITE3_H_.#define
0630: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 _SQLITE3_H_.#inc
0640: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 lude <stdarg.h>
0650: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f /* Needed fo
0660: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e r the definition
0670: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a of va_list */..
0680: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 /*.** Make sure
0690: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 we can call this
06a0: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e stuff from C++.
06b0: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c .*/.#ifdef __cpl
06c0: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 usplus.extern "C
06d0: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a " {.#endif.../*.
06e0: 2a 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 ** Add the abili
06f0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 ty to override '
0700: 65 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 extern'.*/.#ifnd
0710: 65 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e ef SQLITE_EXTERN
0720: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
0730: 5f 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 _EXTERN extern.#
0740: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b endif../*.** Mak
0750: 65 20 73 75 72 65 20 74 68 65 73 65 20 73 79 6d e sure these sym
0760: 62 6f 6c 73 20 77 68 65 72 65 20 6e 6f 74 20 64 bols where not d
0770: 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 efined by some p
0780: 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 0a 2a revious header.*
0790: 2a 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 * file..*/.#ifde
07a0: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
07b0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f .# undef SQLITE_
07c0: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 VERSION.#endif.#
07d0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 ifdef SQLITE_VER
07e0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e SION_NUMBER.# un
07f0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 def SQLITE_VERSI
0800: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 ON_NUMBER.#endif
0810: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
0820: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c : Compile-Time L
0830: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e ibrary Version N
0840: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 umbers.**.** The
0850: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 version of the
0860: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69 SQLite library i
0870: 73 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 s contained in t
0880: 68 65 20 73 71 6c 69 74 65 33 2e 68 0a 2a 2a 20 he sqlite3.h.**
0890: 68 65 61 64 65 72 20 66 69 6c 65 20 69 6e 20 61 header file in a
08a0: 20 23 64 65 66 69 6e 65 20 6e 61 6d 65 64 20 53 #define named S
08b0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 2e 20 20 QLITE_VERSION.
08c0: 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 The SQLITE_VERSI
08d0: 4f 4e 0a 2a 2a 20 6d 61 63 72 6f 20 72 65 73 6f ON.** macro reso
08e0: 6c 76 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67 lves to a string
08f0: 20 63 6f 6e 73 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a constant..**.**
0900: 20 54 68 65 20 66 6f 72 6d 61 74 20 6f 66 20 74 The format of t
0910: 68 65 20 76 65 72 73 69 6f 6e 20 73 74 72 69 6e he version strin
0920: 67 20 69 73 20 22 58 2e 59 2e 5a 22 2c 20 77 68 g is "X.Y.Z", wh
0930: 65 72 65 0a 2a 2a 20 58 20 69 73 20 74 68 65 20 ere.** X is the
0940: 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 major version nu
0950: 6d 62 65 72 2c 20 59 20 69 73 20 74 68 65 20 6d mber, Y is the m
0960: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d inor version num
0970: 62 65 72 20 61 6e 64 20 5a 0a 2a 2a 20 69 73 20 ber and Z.** is
0980: 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 the release numb
0990: 65 72 2e 20 20 54 68 65 20 58 2e 59 2e 5a 20 6d er. The X.Y.Z m
09a0: 69 67 68 74 20 62 65 20 66 6f 6c 6c 6f 77 65 64 ight be followed
09b0: 20 62 79 20 22 61 6c 70 68 61 22 20 6f 72 20 22 by "alpha" or "
09c0: 62 65 74 61 22 2e 0a 2a 2a 20 46 6f 72 20 65 78 beta"..** For ex
09d0: 61 6d 70 6c 65 20 22 33 2e 31 2e 31 62 65 74 61 ample "3.1.1beta
09e0: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 58 20 76 "..**.** The X v
09f0: 61 6c 75 65 20 69 73 20 61 6c 77 61 79 73 20 33 alue is always 3
0a00: 20 69 6e 20 53 51 4c 69 74 65 2e 20 20 54 68 65 in SQLite. The
0a10: 20 58 20 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 X value only ch
0a20: 61 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20 62 61 anges when.** ba
0a30: 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
0a40: 69 6c 69 74 79 20 69 73 20 62 72 6f 6b 65 6e 20 ility is broken
0a50: 61 6e 64 20 77 65 20 69 6e 74 65 6e 64 20 74 6f and we intend to
0a60: 20 6e 65 76 65 72 20 62 72 65 61 6b 0a 2a 2a 20 never break.**
0a70: 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
0a80: 69 62 69 6c 69 74 79 2e 20 20 54 68 65 20 59 20 ibility. The Y
0a90: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 value only chang
0aa0: 65 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65 es when.** there
0ab0: 20 61 72 65 20 6d 61 6a 6f 72 20 66 65 61 74 75 are major featu
0ac0: 72 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 re enhancements
0ad0: 74 68 61 74 20 61 72 65 20 66 6f 72 77 61 72 64 that are forward
0ae0: 73 20 63 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 s compatible.**
0af0: 62 75 74 20 6e 6f 74 20 62 61 63 6b 77 61 72 64 but not backward
0b00: 73 20 63 6f 6d 70 61 74 69 62 6c 65 2e 20 20 54 s compatible. T
0b10: 68 65 20 5a 20 76 61 6c 75 65 20 69 73 20 69 6e he Z value is in
0b20: 63 72 65 6d 65 6e 74 65 64 20 77 69 74 68 0a 2a cremented with.*
0b30: 2a 20 65 61 63 68 20 72 65 6c 65 61 73 65 20 62 * each release b
0b40: 75 74 20 72 65 73 65 74 73 20 62 61 63 6b 20 74 ut resets back t
0b50: 6f 20 30 20 77 68 65 6e 20 59 20 69 73 20 69 6e o 0 when Y is in
0b60: 63 72 65 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a cremented..**.**
0b70: 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 The SQLITE_VERS
0b80: 49 4f 4e 5f 4e 55 4d 42 45 52 20 69 73 20 61 6e ION_NUMBER is an
0b90: 20 69 6e 74 65 67 65 72 20 77 69 74 68 20 74 68 integer with th
0ba0: 65 20 76 61 6c 75 65 20 0a 2a 2a 20 28 58 2a 31 e value .** (X*1
0bb0: 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20 000000 + Y*1000
0bc0: 2b 20 5a 29 2e 20 46 6f 72 20 65 78 61 6d 70 6c + Z). For exampl
0bd0: 65 2c 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 22 e, for version "
0be0: 33 2e 31 2e 31 62 65 74 61 22 2c 20 0a 2a 2a 20 3.1.1beta", .**
0bf0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
0c00: 55 4d 42 45 52 20 69 73 20 73 65 74 20 74 6f 20 UMBER is set to
0c10: 33 30 30 31 30 30 31 2e 20 54 6f 20 64 65 74 65 3001001. To dete
0c20: 63 74 20 69 66 20 74 68 65 79 20 61 72 65 20 75 ct if they are u
0c30: 73 69 6e 67 20 0a 2a 2a 20 76 65 72 73 69 6f 6e sing .** version
0c40: 20 33 2e 31 2e 31 20 6f 72 20 67 72 65 61 74 65 3.1.1 or greate
0c50: 72 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d r at compile tim
0c60: 65 2c 20 70 72 6f 67 72 61 6d 73 20 6d 61 79 20 e, programs may
0c70: 75 73 65 20 74 68 65 20 74 65 73 74 20 0a 2a 2a use the test .**
0c80: 20 28 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e (SQLITE_VERSION
0c90: 5f 4e 55 4d 42 45 52 3e 3d 33 30 30 31 30 30 31 _NUMBER>=3001001
0ca0: 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 )..**.** See als
0cb0: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 o: [sqlite3_libv
0cc0: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 ersion()] and [s
0cd0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
0ce0: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2f 0a n_number()]..*/.
0cf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 #define SQLITE_V
0d00: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 20 22 ERSION "
0d10: 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e --VERS--".#defin
0d20: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e e SQLITE_VERSION
0d30: 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f _NUMBER --VERSIO
0d40: 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a N-NUMBER--../*.*
0d50: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
0d60: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 Time Library Ver
0d70: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a sion Numbers.**.
0d80: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
0d90: 73 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 20 s return values
0da0: 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 74 68 equivalent to th
0db0: 65 20 68 65 61 64 65 72 20 63 6f 6e 73 74 61 6e e header constan
0dc0: 74 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 ts.** [SQLITE_VE
0dd0: 52 53 49 4f 4e 5d 20 61 6e 64 20 5b 53 51 4c 49 RSION] and [SQLI
0de0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
0df0: 52 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 R]. The values
0e00: 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74 returned.** by t
0e10: 68 69 73 20 72 6f 75 74 69 6e 65 73 20 73 68 6f his routines sho
0e20: 75 6c 64 20 6f 6e 6c 79 20 62 65 20 64 69 66 66 uld only be diff
0e30: 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 68 erent from the h
0e40: 65 61 64 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 eader values.**
0e50: 69 66 20 79 6f 75 20 63 6f 6d 70 69 6c 65 20 79 if you compile y
0e60: 6f 75 72 20 70 72 6f 67 72 61 6d 20 75 73 69 6e our program usin
0e70: 67 20 61 6e 20 73 71 6c 69 74 65 33 2e 68 20 68 g an sqlite3.h h
0e80: 65 61 64 65 72 20 66 72 6f 6d 20 61 0a 2a 2a 20 eader from a.**
0e90: 64 69 66 66 65 72 65 6e 74 20 76 65 72 73 69 6f different versio
0ea0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 n of SQLite that
0eb0: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 the version of
0ec0: 74 68 65 20 6c 69 62 72 61 72 79 20 79 6f 75 0a the library you.
0ed0: 2a 2a 20 6c 69 6e 6b 20 61 67 61 69 6e 73 74 2e ** link against.
0ee0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
0ef0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 e3_version[] str
0f00: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e ing constant con
0f10: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f tains the text o
0f20: 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 f the.** [SQLITE
0f30: 5f 56 45 52 53 49 4f 4e 5d 20 73 74 72 69 6e 67 _VERSION] string
0f40: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c . The sqlite3_l
0f50: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 ibversion() func
0f60: 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20 tion returns.**
0f70: 61 20 70 6f 69 6e 65 72 20 74 6f 20 74 68 65 20 a poiner to the
0f80: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b sqlite3_version[
0f90: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e ] string constan
0fa0: 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e t. The function
0fb0: 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 .** is provided
0fc0: 66 6f 72 20 44 4c 4c 20 75 73 65 72 73 20 77 68 for DLL users wh
0fd0: 6f 20 63 61 6e 20 6f 6e 6c 79 20 61 63 63 65 73 o can only acces
0fe0: 73 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 s functions and
0ff0: 6e 6f 74 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 not.** constants
1000: 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e within the DLL.
1010: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 .*/.SQLITE_EXTER
1020: 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c N const char sql
1030: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a ite3_version[];.
1040: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
1050: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 te3_libversion(v
1060: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 oid);.int sqlite
1070: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 3_libversion_num
1080: 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a ber(void);../*.*
1090: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
10a0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 base Connection
10b0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 45 61 63 Handle.**.** Eac
10c0: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 h open SQLite da
10d0: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73 tabase is repres
10e0: 65 6e 74 65 64 20 62 79 20 70 6f 69 6e 74 65 72 ented by pointer
10f0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
1100: 6f 66 20 74 68 65 0a 2a 2a 20 6f 70 61 71 75 65 of the.** opaque
1110: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 structure named
1120: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 "sqlite3". It
1130: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 is useful to thi
1140: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 nk of an sqlite3
1150: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 .** pointer as a
1160: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b n object. The [
1170: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
1180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
1190: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
11a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
11b0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 interfaces are i
11c0: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 0a ts constructors.
11d0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
11e0: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 74 73 20 close()] is its
11f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 destructor. The
1200: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 re are many othe
1210: 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 r interfaces.**
1220: 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74 65 (such as [sqlite
1230: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 3_prepare_v2()],
1240: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
1250: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e _function()], an
1260: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 d.** [sqlite3_bu
1270: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f sy_timeout()] to
1280: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 name but three)
1290: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 that are method
12a0: 73 20 6f 6e 20 74 68 69 73 0a 2a 2a 20 6f 62 6a s on this.** obj
12b0: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ect..*/.typedef
12c0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 struct sqlite3 s
12d0: 71 6c 69 74 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 qlite3;.../*.**
12e0: 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 CAPI3REF: 64-Bit
12f0: 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a Integer Types.*
1300: 2a 0a 2a 2a 20 53 6f 6d 65 20 63 6f 6d 70 69 6c *.** Some compil
1310: 65 72 73 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f ers do not suppo
1320: 72 74 20 74 68 65 20 22 6c 6f 6e 67 20 6c 6f 6e rt the "long lon
1330: 67 22 20 64 61 74 61 74 79 70 65 2e 20 20 53 6f g" datatype. So
1340: 20 77 65 20 68 61 76 65 0a 2a 2a 20 74 6f 20 64 we have.** to d
1350: 6f 20 63 6f 6d 70 69 6c 65 72 2d 73 70 65 63 69 o compiler-speci
1360: 66 69 63 20 74 79 70 65 64 65 66 73 20 66 6f 72 fic typedefs for
1370: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 64-bit signed a
1380: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 nd unsigned inte
1390: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 gers..**.** Many
13a0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
13b0: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 71 75 e functions requ
13c0: 69 72 65 20 61 20 36 34 2d 62 69 74 20 69 6e 74 ire a 64-bit int
13d0: 65 67 65 72 20 61 72 67 75 6d 65 6e 74 73 2e 0a eger arguments..
13e0: 2a 2a 20 54 68 6f 73 65 20 69 6e 74 65 72 66 61 ** Those interfa
13f0: 63 65 73 20 61 72 65 20 64 65 63 6c 61 72 65 64 ces are declared
1400: 20 75 73 69 6e 67 20 74 68 69 73 20 74 79 70 65 using this type
1410: 64 65 66 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 def..*/.#ifdef S
1420: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 QLITE_INT64_TYPE
1430: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 . typedef SQLIT
1440: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c E_INT64_TYPE sql
1450: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 ite_int64;. typ
1460: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 edef unsigned SQ
1470: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 LITE_INT64_TYPE
1480: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
1490: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 elif defined(_MS
14a0: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 C_VER) || define
14b0: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a d(__BORLANDC__).
14c0: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 typedef __int6
14d0: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 4 sqlite_int64;.
14e0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e typedef unsign
14f0: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 ed __int64 sqlit
1500: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a e_uint64;.#else.
1510: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c typedef long l
1520: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 ong int sqlite_i
1530: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 nt64;. typedef
1540: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f unsigned long lo
1550: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 ng int sqlite_ui
1560: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 nt64;.#endif.typ
1570: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 edef sqlite_int6
1580: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 4 sqlite3_int64;
1590: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f .typedef sqlite_
15a0: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 uint64 sqlite3_u
15b0: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 int64;../*.** If
15c0: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 compiling for a
15d0: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 processor that
15e0: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 lacks floating p
15f0: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a oint support,.**
1600: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 substitute inte
1610: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 ger for floating
1620: 2d 70 6f 69 6e 74 0a 2a 2f 0a 23 69 66 64 65 66 -point.*/.#ifdef
1630: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f SQLITE_OMIT_FLO
1640: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 ATING_POINT.# de
1650: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 fine double sqli
1660: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 te3_int64.#endif
1670: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1680: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 : Closing A Data
1690: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a base Connection.
16a0: 2a 2a 0a 2a 2a 20 43 61 6c 6c 20 74 68 69 73 20 **.** Call this
16b0: 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 function with a
16c0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 pointer to a str
16d0: 75 63 74 75 72 65 20 74 68 61 74 20 77 61 73 20 ucture that was
16e0: 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 previously.** re
16f0: 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c turned from [sql
1700: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
1710: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
1720: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
1730: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 _open_v2()] and
1740: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
1750: 67 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 g database will
1760: 62 79 0a 2a 2a 20 63 6c 6f 73 65 64 2e 0a 2a 2a by.** closed..**
1770: 0a 2a 2a 20 41 6c 6c 20 53 51 4c 20 73 74 61 74 .** All SQL stat
1780: 65 6d 65 6e 74 73 20 70 72 65 70 61 72 65 64 20 ements prepared
1790: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 using [sqlite3_p
17a0: 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a repare_v2()] or.
17b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
17c0: 61 72 65 31 36 5f 76 32 28 29 5d 20 6d 75 73 74 are16_v2()] must
17d0: 20 62 65 20 64 65 73 74 72 6f 79 65 64 20 75 73 be destroyed us
17e0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
17f0: 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 62 65 66 6f alize()].** befo
1800: 72 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 re this routine
1810: 69 73 20 63 61 6c 6c 65 64 2e 20 4f 74 68 65 72 is called. Other
1820: 77 69 73 65 2c 20 53 51 4c 49 54 45 5f 42 55 53 wise, SQLITE_BUS
1830: 59 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e Y is returned an
1840: 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 d the.** databas
1850: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 72 65 6d e connection rem
1860: 61 69 6e 73 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a 2a ains open..**.**
1870: 20 50 61 73 73 69 6e 67 20 74 68 69 73 20 72 6f Passing this ro
1880: 75 74 69 6e 65 20 61 20 64 61 74 61 62 61 73 65 utine a database
1890: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
18a0: 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 has already bee
18b0: 6e 0a 2a 2a 20 63 6c 6f 73 65 64 20 72 65 73 75 n.** closed resu
18c0: 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 lts in undefined
18d0: 20 62 65 68 61 76 69 6f 72 2e 20 20 49 66 20 6f behavior. If o
18e0: 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 ther interfaces
18f0: 74 68 61 74 0a 2a 2a 20 72 65 66 65 72 65 6e 63 that.** referenc
1900: 65 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 e the same datab
1910: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 ase connection a
1920: 72 65 20 70 65 6e 64 69 6e 67 20 28 65 69 74 68 re pending (eith
1930: 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 73 61 6d er in the.** sam
1940: 65 20 74 68 72 65 61 64 20 6f 72 20 69 6e 20 64 e thread or in d
1950: 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 ifferent threads
1960: 29 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 ) when this rout
1970: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 0a 2a ine is called,.*
1980: 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 * then the behav
1990: 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
19a0: 20 61 6e 64 20 69 73 20 61 6c 6d 6f 73 74 20 63 and is almost c
19b0: 65 72 74 61 69 6e 6c 79 20 75 6e 64 65 73 69 72 ertainly undesir
19c0: 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c able..*/.int sql
19d0: 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 ite3_close(sqlit
19e0: 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 e3 *);../*.** Th
19f0: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c e type for a cal
1a00: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a lback function..
1a10: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 ** This is legac
1a20: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 y and deprecated
1a30: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 . It is include
1a40: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c d for historical
1a50: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 .** compatibilit
1a60: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 y and is not doc
1a70: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 umented..*/.type
1a80: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 def int (*sqlite
1a90: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 3_callback)(void
1aa0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 *,int,char**, ch
1ab0: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ar**);../*.** CA
1ac0: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 PI3REF: One-Step
1ad0: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e Query Execution
1ae0: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a Interface.**.**
1af0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
1b00: 69 73 20 75 73 65 64 20 74 6f 20 64 6f 20 61 20 is used to do a
1b10: 6f 6e 65 2d 74 69 6d 65 20 65 76 61 6c 75 61 74 one-time evaluat
1b20: 61 74 69 6f 6e 20 6f 66 20 7a 65 72 6f 0a 2a 2a ation of zero.**
1b30: 20 6f 72 20 6d 6f 72 65 20 53 51 4c 20 73 74 61 or more SQL sta
1b40: 74 65 6d 65 6e 74 73 2e 20 20 55 54 46 2d 38 20 tements. UTF-8
1b50: 74 65 78 74 20 6f 66 20 74 68 65 20 53 51 4c 20 text of the SQL
1b60: 73 74 61 74 65 6d 65 6e 74 73 20 74 6f 0a 2a 2a statements to.**
1b70: 20 62 65 20 65 76 61 6c 75 74 65 64 20 69 73 20 be evaluted is
1b80: 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 passed in as the
1b90: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
1ba0: 72 2e 20 20 54 68 65 20 73 74 61 74 65 6d 65 6e r. The statemen
1bb0: 74 73 0a 2a 2a 20 61 72 65 20 70 72 65 70 61 72 ts.** are prepar
1bc0: 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75 73 ed one by one us
1bd0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ing [sqlite3_pre
1be0: 70 61 72 65 28 29 5d 2c 20 65 76 61 6c 75 61 74 pare()], evaluat
1bf0: 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c ed.** using [sql
1c00: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 74 68 ite3_step()], th
1c10: 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73 69 en destroyed usi
1c20: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
1c30: 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 lize()]..**.** I
1c40: 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 f one or more of
1c50: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
1c60: 6e 74 73 20 61 72 65 20 71 75 65 72 69 65 73 2c nts are queries,
1c70: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 61 6c then.** the cal
1c80: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 lback function s
1c90: 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
1ca0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 3rd parameter is
1cb0: 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 .** invoked once
1cc0: 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 for each row of
1cd0: 20 74 68 65 20 71 75 65 72 79 20 72 65 73 75 6c the query resul
1ce0: 74 2e 20 20 54 68 69 73 20 63 61 6c 6c 62 61 63 t. This callbac
1cf0: 6b 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 72 6d k.** should norm
1d00: 61 6c 6c 79 20 72 65 74 75 72 6e 20 30 2e 20 20 ally return 0.
1d10: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
1d20: 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 returns a non-ze
1d30: 72 6f 0a 2a 2a 20 76 61 6c 75 65 20 74 68 65 6e ro.** value then
1d40: 20 74 68 65 20 71 75 65 72 79 20 69 73 20 61 62 the query is ab
1d50: 6f 72 74 65 64 2c 20 61 6c 6c 20 73 75 62 73 65 orted, all subse
1d60: 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d quent SQL statem
1d70: 65 6e 74 73 0a 2a 2a 20 61 72 65 20 73 6b 69 70 ents.** are skip
1d80: 70 65 64 20 61 6e 64 20 74 68 65 20 73 71 6c 69 ped and the sqli
1d90: 74 65 33 5f 65 78 65 63 28 29 20 66 75 6e 63 74 te3_exec() funct
1da0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 ion returns the
1db0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 2e 0a 2a 2a SQLITE_ABORT..**
1dc0: 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 .** The 4th para
1dd0: 6d 65 74 65 72 20 74 6f 20 74 68 69 73 20 69 6e meter to this in
1de0: 74 65 72 66 61 63 65 20 69 73 20 61 6e 20 61 72 terface is an ar
1df0: 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 20 bitrary pointer
1e00: 74 68 61 74 20 69 73 0a 2a 2a 20 70 61 73 73 65 that is.** passe
1e10: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 d through to the
1e20: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
1e30: 6f 6e 20 61 73 20 69 74 73 20 66 69 72 73 74 20 on as its first
1e40: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
1e50: 20 54 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 The 2nd paramet
1e60: 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 er to the callba
1e70: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ck function is t
1e80: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
1e90: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 71 columns in the q
1ea0: 75 65 72 79 20 72 65 73 75 6c 74 2e 20 20 54 68 uery result. Th
1eb0: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
1ec0: 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a to the callback.
1ed0: 2a 2a 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f ** is an array o
1ee0: 66 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e f strings holdin
1ef0: 67 20 74 68 65 20 76 61 6c 75 65 73 20 66 6f 72 g the values for
1f00: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 each column.**
1f10: 61 73 20 65 78 74 72 61 63 74 65 64 20 75 73 69 as extracted usi
1f20: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ng [sqlite3_colu
1f30: 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 20 54 mn_text()]..** T
1f40: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
1f50: 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
1f60: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 is an array of
1f70: 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 62 74 61 69 strings.** obtai
1f80: 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ned using [sqlit
1f90: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
1fa0: 5d 20 61 6e 64 20 68 6f 6c 64 69 6e 67 0a 2a 2a ] and holding.**
1fb0: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 65 61 the names of ea
1fc0: 63 68 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a ch column..**.**
1fd0: 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 The callback fu
1fe0: 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 4e 55 nction may be NU
1ff0: 4c 4c 2c 20 65 76 65 6e 20 66 6f 72 20 71 75 65 LL, even for que
2000: 72 69 65 73 2e 20 20 41 20 4e 55 4c 4c 0a 2a 2a ries. A NULL.**
2010: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 callback is not
2020: 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 74 20 6a an error. It j
2030: 75 73 74 20 6d 65 61 6e 73 20 74 68 61 74 20 6e ust means that n
2040: 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 77 69 o callback.** wi
2050: 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a ll be invoked..*
2060: 2a 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f 72 *.** If an error
2070: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 occurs while pa
2080: 72 73 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 rsing or evaluat
2090: 69 6e 67 20 74 68 65 20 53 51 4c 20 28 62 75 74 ing the SQL (but
20a0: 0a 2a 2a 20 6e 6f 74 20 77 68 69 6c 65 20 65 78 .** not while ex
20b0: 65 63 75 74 69 6e 67 20 74 68 65 20 63 61 6c 6c ecuting the call
20c0: 62 61 63 6b 29 20 74 68 65 6e 20 61 6e 20 61 70 back) then an ap
20d0: 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 0a propriate error.
20e0: 2a 2a 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 ** message is wr
20f0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 itten into memor
2100: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
2110: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
2120: 29 5d 20 61 6e 64 0a 2a 2a 20 2a 65 72 72 6d 73 )] and.** *errms
2130: 67 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 g is made to poi
2140: 6e 74 20 74 6f 20 74 68 61 74 20 6d 65 73 73 61 nt to that messa
2150: 67 65 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 ge. The calling
2160: 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 73 20 function.** is
2170: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 responsible for
2180: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f freeing the memo
2190: 72 79 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 ry that holds th
21a0: 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 e error.** messa
21b0: 67 65 2e 20 20 20 55 73 65 20 5b 73 71 6c 69 74 ge. Use [sqlit
21c0: 65 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 20 74 e3_free()] for t
21d0: 68 69 73 2e 20 20 49 66 20 65 72 72 6d 73 67 3d his. If errmsg=
21e0: 3d 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 6e =NULL,.** then n
21f0: 6f 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 o error message
2200: 69 73 20 65 76 65 72 20 77 72 69 74 74 65 6e 2e is ever written.
2210: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 .**.** The retur
2220: 6e 20 76 61 6c 75 65 20 69 73 20 69 73 20 53 51 n value is is SQ
2230: 4c 49 54 45 5f 4f 4b 20 69 66 20 74 68 65 72 65 LITE_OK if there
2240: 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 20 61 are no errors a
2250: 6e 64 0a 2a 2a 20 73 6f 6d 65 20 6f 74 68 65 72 nd.** some other
2260: 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 [SQLITE_OK | re
2270: 74 75 72 6e 20 63 6f 64 65 5d 20 69 66 20 74 68 turn code] if th
2280: 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2e ere is an error.
2290: 20 20 0a 2a 2a 20 54 68 65 20 70 61 72 74 69 63 .** The partic
22a0: 75 6c 61 72 20 72 65 74 75 72 6e 20 76 61 6c 75 ular return valu
22b0: 65 20 64 65 70 65 6e 64 73 20 6f 6e 20 74 68 65 e depends on the
22c0: 20 74 79 70 65 20 6f 66 20 65 72 72 6f 72 2e 20 type of error.
22d0: 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 .**.*/.int sqlit
22e0: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 e3_exec(. sqlit
22f0: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 e3*,
2300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2310: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e /* An open
2320: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 database */. c
2330: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 onst char *sql,
2340: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2350: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c /* SQL
2360: 20 74 6f 20 62 65 20 65 76 61 6c 75 74 65 64 20 to be evaluted
2370: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 */. int (*callb
2380: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 ack)(void*,int,c
2390: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 har**,char**),
23a0: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 /* Callback func
23b0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a tion */. void *
23c0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
23d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
23e0: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 /* 1st argu
23f0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b ment to callback
2400: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 */. char **err
2410: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 msg
2420: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2430: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 /* Error msg wr
2440: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b itten here */.);
2450: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2460: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a : Result Codes.*
2470: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 * KEYWORDS: SQLI
2480: 54 45 5f 4f 4b 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 TE_OK.**.** Many
2490: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e SQLite function
24a0: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 s return an inte
24b0: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 ger result code
24c0: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f from the set sho
24d0: 77 6e 0a 2a 2a 20 61 62 6f 76 65 20 69 6e 20 6f wn.** above in o
24e0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 rder to indicate
24f0: 73 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 s success or fai
2500: 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 lure..**.** The
2510: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 62 6f result codes abo
2520: 76 65 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 ve are the only
2530: 6f 6e 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 ones returned by
2540: 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 0a 2a SQLite in its.*
2550: 2a 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 * default config
2560: 75 72 61 74 69 6f 6e 2e 20 20 48 6f 77 65 76 65 uration. Howeve
2570: 72 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f r, the [sqlite3_
2580: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f extended_result_
2590: 63 6f 64 65 73 28 29 5d 0a 2a 2a 20 41 50 49 20 codes()].** API
25a0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 73 can be used to s
25b0: 65 74 20 61 20 64 61 74 61 62 61 73 65 20 63 6f et a database co
25c0: 6e 6e 65 63 74 6f 69 6e 20 74 6f 20 72 65 74 75 nnectoin to retu
25d0: 72 6e 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 rn more detailed
25e0: 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 64 65 73 .** result codes
25f0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
2600: 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f : [SQLITE_IOERR_
2610: 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 READ | extended
2620: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2a result codes].**
2630: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
2640: 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 TE_OK
2650: 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 0 /* Successfu
2660: 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 l result */./* b
2670: 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f eginning-of-erro
2680: 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 r-codes */.#defi
2690: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 ne SQLITE_ERROR
26a0: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 1 /* SQ
26b0: 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 L error or missi
26c0: 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 ng database */.#
26d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
26e0: 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f TERNAL 2 /
26f0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 49 6e 74 65 * NOT USED. Inte
2700: 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 rnal logic error
2710: 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 in SQLite */.#d
2720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 efine SQLITE_PER
2730: 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a M 3 /*
2740: 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 Access permissi
2750: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 on denied */.#de
2760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 fine SQLITE_ABOR
2770: 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 T 4 /*
2780: 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 Callback routine
2790: 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 requested an ab
27a0: 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ort */.#define S
27b0: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 QLITE_BUSY
27c0: 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 5 /* The da
27d0: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c tabase file is l
27e0: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 ocked */.#define
27f0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 SQLITE_LOCKED
2800: 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 6 /* A ta
2810: 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 ble in the datab
2820: 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f ase is locked */
2830: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2840: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 NOMEM 7
2850: 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 /* A malloc() f
2860: 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 ailed */.#define
2870: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 SQLITE_READONLY
2880: 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 8 /* Atte
2890: 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 mpt to write a r
28a0: 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 eadonly database
28b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
28c0: 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 TE_INTERRUPT
28d0: 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 9 /* Operation
28e0: 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 terminated by s
28f0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
2900: 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ()*/.#define SQL
2910: 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 ITE_IOERR
2920: 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 10 /* Some kin
2930: 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 d of disk I/O er
2940: 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a ror occurred */.
2950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
2960: 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20 ORRUPT 11
2970: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 /* The database
2980: 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 disk image is ma
2990: 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 lformed */.#defi
29a0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 ne SQLITE_NOTFOU
29b0: 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f ND 12 /* NO
29c0: 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 T USED. Table or
29d0: 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e record not foun
29e0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
29f0: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 ITE_FULL
2a00: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 13 /* Insertio
2a10: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 n failed because
2a20: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c database is ful
2a30: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
2a40: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 ITE_CANTOPEN
2a50: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 14 /* Unable t
2a60: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 o open the datab
2a70: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 ase file */.#def
2a80: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f ine SQLITE_PROTO
2a90: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e COL 15 /* N
2aa0: 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61 73 OT USED. Databas
2ab0: 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 e lock protocol
2ac0: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 error */.#define
2ad0: 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 SQLITE_EMPTY
2ae0: 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 16 /* Data
2af0: 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f base is empty */
2b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2b10: 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 SCHEMA 17
2b20: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
2b30: 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 schema changed
2b40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
2b50: 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 E_TOOBIG 18
2b60: 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 /* String or
2b70: 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a BLOB exceeds siz
2b80: 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 e limit */.#defi
2b90: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
2ba0: 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 AINT 19 /* Ab
2bb0: 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 74 72 ort due to contr
2bc0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a aint violation *
2bd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2be0: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 _MISMATCH 20
2bf0: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d /* Data type m
2c00: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 ismatch */.#defi
2c10: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 ne SQLITE_MISUSE
2c20: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 21 /* Li
2c30: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 brary used incor
2c40: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e rectly */.#defin
2c50: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 e SQLITE_NOLFS
2c60: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 22 /* Use
2c70: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f s OS features no
2c80: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 t supported on h
2c90: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ost */.#define S
2ca0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 QLITE_AUTH
2cb0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 23 /* Author
2cc0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a ization denied *
2cd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2ce0: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 _FORMAT 24
2cf0: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 /* Auxiliary d
2d00: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 atabase format e
2d10: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
2d20: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 SQLITE_RANGE
2d30: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 25 /* 2nd p
2d40: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
2d50: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 te3_bind out of
2d60: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 range */.#define
2d70: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 SQLITE_NOTADB
2d80: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 26 /* File
2d90: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 opened that is
2da0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 not a database f
2db0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ile */.#define S
2dc0: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 QLITE_ROW
2dd0: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 100 /* sqlite
2de0: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 3_step() has ano
2df0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a ther row ready *
2e00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2e10: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 _DONE 101
2e20: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 /* sqlite3_ste
2e30: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 p() has finished
2e40: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a executing */./*
2e50: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f end-of-error-co
2e60: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 des */../*.** CA
2e70: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 PI3REF: Extended
2e80: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a Result Codes.**
2e90: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 .** In its defau
2ea0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e lt configuration
2eb0: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 , SQLite API rou
2ec0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 tines return one
2ed0: 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a of 26 integer.*
2ee0: 2a 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 64 * result codes d
2ef0: 65 73 63 72 69 62 65 64 20 61 74 20 72 65 73 75 escribed at resu
2f00: 6c 74 2d 63 6f 64 65 73 2e 20 20 48 6f 77 65 76 lt-codes. Howev
2f10: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 er, experience h
2f20: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 0a 2a 2a as shown that.**
2f30: 20 6d 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 many of these r
2f40: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 esult codes are
2f50: 74 6f 6f 20 63 6f 75 72 73 65 2d 67 72 61 69 6e too course-grain
2f60: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 ed. They do not
2f70: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d provide as.** m
2f80: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 uch information
2f90: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 about problems a
2fa0: 73 20 75 73 65 72 73 20 6d 69 67 68 74 20 6c 69 s users might li
2fb0: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 ke. In an effor
2fc0: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 t to.** address
2fd0: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 this, newer vers
2fe0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 ions of SQLite (
2ff0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e version 3.3.8 an
3000: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 d later) include
3010: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 .** support for
3020: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c additional resul
3030: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f t codes that pro
3040: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c vide more detail
3050: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a ed information.*
3060: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 * about errors.
3070: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 The extended re
3080: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 sult codes are e
3090: 6e 61 62 6c 65 64 20 28 6f 72 20 64 69 73 61 62 nabled (or disab
30a0: 6c 65 64 29 20 66 6f 72 20 0a 2a 2a 20 65 61 63 led) for .** eac
30b0: 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f h database.** co
30c0: 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 20 74 nnection using t
30d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 he [sqlite3_exte
30e0: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
30f0: 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 20 0a 2a 2a s()] API..** .**
3100: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 Some of the ava
3110: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 ilable extended
3120: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
3130: 20 6c 69 73 74 65 64 20 61 62 6f 76 65 2e 0a 2a listed above..*
3140: 2a 20 57 65 20 65 78 70 65 63 74 20 74 68 65 20 * We expect the
3150: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 number of extend
3160: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 ed result codes
3170: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a will be expand.*
3180: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f * over time. So
3190: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73 ftware that uses
31a0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
31b0: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 codes should ex
31c0: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e pect.** to see n
31d0: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 ew result codes
31e0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
31f0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
3200: 20 0a 2a 2a 20 54 68 65 20 73 79 6d 62 6f 6c 69 .** The symboli
3210: 63 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 c name for an ex
3220: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
3230: 64 65 20 61 6c 77 61 79 73 20 63 6f 6e 74 61 69 de always contai
3240: 6e 73 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 ns a related.**
3250: 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 primary result c
3260: 6f 64 65 20 61 73 20 61 20 70 72 65 66 69 78 2e ode as a prefix.
3270: 20 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74 Primary result
3280: 20 63 6f 64 65 73 20 63 6f 6e 74 61 69 6e 20 61 codes contain a
3290: 20 73 69 6e 67 6c 65 0a 2a 2a 20 22 5f 22 20 63 single.** "_" c
32a0: 68 61 72 61 63 74 65 72 2e 20 20 45 78 74 65 6e haracter. Exten
32b0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
32c0: 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72 20 contain two or
32d0: 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63 74 more "_" charact
32e0: 65 72 73 2e 0a 2a 2a 20 54 68 65 20 6e 75 6d 65 ers..** The nume
32f0: 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 ric value of an
3300: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
3310: 63 6f 64 65 20 63 61 6e 20 62 65 20 63 6f 6e 76 code can be conv
3320: 65 72 74 65 64 20 74 6f 20 69 74 73 0a 2a 2a 20 erted to its.**
3330: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72 corresponding pr
3340: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 imary result cod
3350: 65 20 62 79 20 6d 61 73 6b 69 6e 67 20 6f 66 66 e by masking off
3360: 20 74 68 65 20 6c 6f 77 65 72 20 38 20 62 79 74 the lower 8 byt
3370: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 es..**.** The SQ
3380: 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 LITE_OK result c
3390: 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 ode will never b
33a0: 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 e extended. It
33b0: 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 will always.** b
33c0: 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a e exactly zero..
33d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
33e0: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 E_IOERR_READ
33f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
3400: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 ERR | (1<<8)).#d
3410: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
3420: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 RR_SHORT_READ
3430: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
3440: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
3450: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 SQLITE_IOERR_WR
3460: 49 54 45 20 20 20 20 20 20 20 20 20 28 53 51 4c ITE (SQL
3470: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c ITE_IOERR | (3<<
3480: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
3490: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 TE_IOERR_FSYNC
34a0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
34b0: 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 OERR | (4<<8)).#
34c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
34d0: 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 ERR_DIR_FSYNC
34e0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
34f0: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (5<<8)).#defin
3500: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 e SQLITE_IOERR_T
3510: 52 55 4e 43 41 54 45 20 20 20 20 20 20 28 53 51 RUNCATE (SQ
3520: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c LITE_IOERR | (6<
3530: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
3540: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 ITE_IOERR_FSTAT
3550: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
3560: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a IOERR | (7<<8)).
3570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3580: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 OERR_UNLOCK
3590: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
35a0: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 | (8<<8)).#defi
35b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
35c0: 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53 RDLOCK (S
35d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 QLITE_IOERR | (9
35e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
35f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 LITE_IOERR_DELET
3600: 45 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 E (SQLITE
3610: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 _IOERR | (10<<8)
3620: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
3630: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 _IOERR_BLOCKED
3640: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
3650: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 0a 2f RR | (11<<8))../
3660: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
3670: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 lags For File Op
3680: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a en Operations.**
3690: 0a 2a 2a 20 43 6f 6d 62 69 6e 61 74 69 6f 6e 20 .** Combination
36a0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
36b0: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 bit values are
36c0: 75 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 74 used as the.** t
36d0: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f hird argument to
36e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 the [sqlite3_op
36f0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
3700: 63 65 20 61 6e 64 0a 2a 2a 20 61 73 20 66 6f 75 ce and.** as fou
3710: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rth argument to
3720: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 the xOpen method
3730: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
3740: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
3750: 0a 2a 2a 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 .**.*/.#define S
3760: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
3770: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 NLY 0x00
3780: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 000001.#define S
3790: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
37a0: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 RITE 0x00
37b0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 000002.#define S
37c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
37d0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 E 0x00
37e0: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 000004.#define S
37f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
3800: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 EONCLOSE 0x00
3810: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 000008.#define S
3820: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
3830: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 SIVE 0x00
3840: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 000010.#define S
3850: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
3860: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
3870: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 000100.#define S
3880: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
3890: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
38a0: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 000200.#define S
38b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
38c0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
38d0: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 000400.#define S
38e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
38f0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
3900: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 000800.#define S
3910: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f QLITE_OPEN_SUBJO
3920: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 URNAL 0x00
3930: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 001000.#define S
3940: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 QLITE_OPEN_MASTE
3950: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 R_JOURNAL 0x00
3960: 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 002000../*.** CA
3970: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 PI3REF: Device C
3980: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a haracteristics.*
3990: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 *.** The xDevice
39a0: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74 Capabilities met
39b0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 hod of the [sqli
39c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a te3_io_methods].
39d0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e ** object return
39e0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 s an integer whi
39f0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f ch is a vector o
3a00: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a f the following.
3a10: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 ** bit values ex
3a20: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 pressing I/O cha
3a30: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 racteristics of
3a40: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 the mass storage
3a50: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 .** device that
3a60: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 holds the file t
3a70: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 hat the [sqlite3
3a80: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 _io_methods].**
3a90: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a refers to..**.**
3aa0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
3ab0: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 P_ATOMIC propert
3ac0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c y means that all
3ad0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e writes of.** an
3ae0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 y size are atomi
3af0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 c. The SQLITE_I
3b00: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 OCAP_ATOMICnnn v
3b10: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 alues.** mean th
3b20: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f at writes of blo
3b30: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e cks that are nnn
3b40: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 bytes in size a
3b50: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 nd.** are aligne
3b60: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 d to an address
3b70: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 which is an inte
3b80: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a ger multiple of.
3b90: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 ** nnn are atomi
3ba0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 c. The SQLITE_I
3bb0: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 OCAP_SAFE_APPEND
3bc0: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 value means.**
3bd0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 that when data i
3be0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 s appended to a
3bf0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 file, the data i
3c00: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 s appended.** fi
3c10: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a rst then the siz
3c20: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 e of the file is
3c30: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 extended, never
3c40: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 the other.** wa
3c50: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 y around. The S
3c60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
3c70: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 ENTIAL property
3c80: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e means that.** in
3c90: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 formation is wri
3ca0: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 tten to disk in
3cb0: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 the same order a
3cc0: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 s calls.** to xW
3cd0: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 rite()..*/.#defi
3ce0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
3cf0: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 ATOMIC
3d00: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 0x00000001.#defi
3d10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
3d20: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 ATOMIC512
3d30: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 0x00000002.#defi
3d40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
3d50: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 ATOMIC1K
3d60: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 0x00000004.#defi
3d70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
3d80: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 ATOMIC2K
3d90: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 0x00000008.#defi
3da0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
3db0: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 ATOMIC4K
3dc0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 0x00000010.#defi
3dd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
3de0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 ATOMIC8K
3df0: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 0x00000020.#defi
3e00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
3e10: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 ATOMIC16K
3e20: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 0x00000040.#defi
3e30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
3e40: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 ATOMIC32K
3e50: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 0x00000080.#defi
3e60: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
3e70: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 ATOMIC64K
3e80: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 0x00000100.#defi
3e90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
3ea0: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 SAFE_APPEND
3eb0: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 0x00000200.#defi
3ec0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
3ed0: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 SEQUENTIAL
3ee0: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 0x00000400../*.*
3ef0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 * CAPI3REF: File
3f00: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a Locking Levels.
3f10: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 **.** SQLite use
3f20: 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c s one of the fol
3f30: 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 76 lowing integer v
3f40: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 alues as the sec
3f50: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 ond.** argument
3f60: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 to calls it make
3f70: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 s to the xLock()
3f80: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d and xUnlock() m
3f90: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 ethods.** of an
3fa0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
3fb0: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a ods] object..*/.
3fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
3fd0: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 OCK_NONE
3fe0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
3ff0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 TE_LOCK_SHARED
4000: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
4010: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
4020: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 RVED 2.#def
4030: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ine SQLITE_LOCK_
4040: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a PENDING 3.
4050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
4060: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 OCK_EXCLUSIVE
4070: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 4../*.** CAPI3
4080: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 REF: Synchroniza
4090: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a tion Type Flags.
40a0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 **.** When SQLit
40b0: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 e invokes the xS
40c0: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 ync() method of
40d0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d an [sqlite3_io_m
40e0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 ethods].** objec
40f0: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 t it uses a comb
4100: 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 66 ination of the f
4110: 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 ollowing integer
4120: 20 76 61 6c 75 65 73 20 61 73 0a 2a 2a 20 74 68 values as.** th
4130: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
4140: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 t..**.** When th
4150: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
4160: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 TAONLY flag is u
4170: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 sed, it means th
4180: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f at the.** sync o
4190: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 peration only ne
41a0: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 eds to flush dat
41b0: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 a to mass storag
41c0: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 e. Inode.** inf
41d0: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f ormation need no
41e0: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 20 54 t be flushed. T
41f0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 42 he SQLITE_SYNC_B
4200: 41 52 52 49 45 52 20 66 6c 61 67 0a 2a 2a 20 6d ARRIER flag.** m
4210: 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 6e 6f eans that the no
4220: 74 68 69 6e 67 20 61 63 74 75 61 6c 6c 79 20 6e thing actually n
4230: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 68 eeds to be synch
4240: 65 64 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 ed to mass stora
4250: 67 65 2c 0a 2a 2a 20 62 75 74 20 61 6c 6c 20 77 ge,.** but all w
4260: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 rite operations
4270: 74 68 61 74 20 6f 63 63 75 72 20 62 65 66 6f 72 that occur befor
4280: 65 20 74 68 65 20 62 61 72 72 69 65 72 20 6d 75 e the barrier mu
4290: 73 74 20 63 6f 6d 70 6c 65 74 65 0a 2a 2a 20 62 st complete.** b
42a0: 65 66 6f 72 65 20 61 6e 79 20 77 72 69 74 65 20 efore any write
42b0: 6f 70 65 72 61 74 69 6f 6e 73 20 74 68 61 74 20 operations that
42c0: 6f 63 63 75 72 20 61 66 74 65 72 20 74 68 65 20 occur after the
42d0: 62 61 72 72 69 65 72 20 62 65 67 69 6e 2e 0a 2a barrier begin..*
42e0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e * The SQLITE_SYN
42f0: 43 5f 4e 4f 52 4d 41 4c 20 6d 65 61 6e 73 20 74 C_NORMAL means t
4300: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 o use normal fsy
4310: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a nc() semantics..
4320: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 ** The SQLITE_SY
4330: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61 NC_FULL flag mea
4340: 6e 73 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 ns to use Mac OS
4350: 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e -X style fullsyn
4360: 63 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 20 c.** instead of
4370: 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 fsync()..*/.#def
4380: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ine SQLITE_SYNC_
4390: 42 41 52 52 49 45 52 20 20 20 20 20 20 20 30 78 BARRIER 0x
43a0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 00001.#define SQ
43b0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
43c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 0x00002.
43d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
43e0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 YNC_FULL
43f0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 0x00003.#defin
4400: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
4410: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 TAONLY 0x00
4420: 30 31 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 010.../*.** CAPI
4430: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 3REF: OS Interfa
4440: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e ce Open File Han
4450: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 dle.**.** An [sq
4460: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
4470: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e ct represents an
4480: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 open file in th
4490: 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63 e OS.** interfac
44a0: 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69 e layer. Indivi
44b0: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 dual OS interfac
44c0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
44d0: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 s will.** want t
44e0: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 o subclass this
44f0: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 object by append
4500: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 ing additional f
4510: 69 65 6c 64 73 0a 2a 2a 20 6f 66 20 74 68 65 69 ields.** of thei
4520: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 r own use. The
4530: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 pMethods entry i
4540: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
4550: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f n.** [sqlite3_io
4560: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
4570: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 that defines me
4580: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 thods for perfor
4590: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 ming.** I/O oper
45a0: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 ations on the op
45b0: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 en file..*/.type
45c0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
45d0: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f e3_file sqlite3_
45e0: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c file;.struct sql
45f0: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f ite3_file {. co
4600: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 nst struct sqlit
4610: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 e3_io_methods *p
4620: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 Methods; /* Met
4630: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e hods for an open
4640: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a file */.};../*.
4650: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
4660: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 Interface File V
4670: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f irtual Methods O
4680: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 bject.**.** Ever
4690: 79 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 y open file in t
46a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d he [sqlite3_vfs]
46b0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63 6f xOpen method co
46c0: 6e 74 61 69 6e 73 20 61 20 70 6f 69 6e 74 65 72 ntains a pointer
46d0: 20 74 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e to.** an instan
46e0: 63 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ce of the follow
46f0: 69 6e 67 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 ing object. Thi
4700: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 s object defines
4710: 20 74 68 65 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 the.** methods
4720: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 used to perform
4730: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f various operatio
4740: 6e 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f ns against the o
4750: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 pen file..**.**
4760: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 The flags argume
4770: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 nt to xSync may
4780: 62 65 20 6f 6e 65 20 6f 66 20 53 51 4c 49 54 45 be one of SQLITE
4790: 5f 53 59 4e 43 5f 42 41 52 52 49 45 52 2c 0a 2a _SYNC_BARRIER,.*
47a0: 2a 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f * SQLITE_SYNC_NO
47b0: 52 4d 41 4c 2c 20 53 51 4c 49 54 45 5f 53 59 4e RMAL, SQLITE_SYN
47c0: 43 5f 46 55 4c 4c 2e 20 20 54 68 65 20 66 69 72 C_FULL. The fir
47d0: 73 74 20 63 68 6f 69 63 65 20 6d 65 61 6e 73 20 st choice means
47e0: 74 68 61 74 0a 2a 2a 20 64 61 74 61 20 69 73 20 that.** data is
47f0: 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 not necessarily
4800: 73 79 6e 63 65 64 20 74 6f 20 64 69 73 6b 20 63 synced to disk c
4810: 6f 6d 70 6c 65 74 65 6c 79 2c 20 6f 6e 6c 79 20 ompletely, only
4820: 74 68 61 74 0a 2a 2a 20 61 6c 6c 20 77 72 69 74 that.** all writ
4830: 65 73 20 74 68 61 74 20 6f 63 63 75 72 20 62 65 es that occur be
4840: 66 6f 72 65 20 74 68 65 20 73 79 6e 63 20 63 6f fore the sync co
4850: 6d 70 6c 65 74 65 20 62 65 66 6f 72 65 20 61 6e mplete before an
4860: 79 0a 2a 2a 20 77 72 69 74 65 73 20 74 68 61 74 y.** writes that
4870: 20 6f 63 63 75 72 20 61 66 74 65 72 20 74 68 65 occur after the
4880: 20 73 79 6e 63 2e 20 20 54 68 65 20 73 65 63 6f sync. The seco
4890: 6e 64 20 66 6c 61 67 20 69 73 20 74 68 65 0a 2a nd flag is the.*
48a0: 2a 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 * normal fsync()
48b0: 2e 20 20 54 68 65 20 74 68 69 72 64 20 66 6c 61 . The third fla
48c0: 67 20 69 73 20 61 20 4f 53 2d 58 20 73 74 79 6c g is a OS-X styl
48d0: 65 20 66 75 6c 6c 73 79 6e 63 2e 0a 2a 2a 20 54 e fullsync..** T
48e0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 he SQLITE_SYNC_D
48f0: 41 54 41 20 66 6c 61 67 20 6d 61 79 20 62 65 20 ATA flag may be
4900: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 ORed in to indic
4910: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 0a 2a 2a ate that only.**
4920: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 the data of the
4930: 20 66 69 6c 65 20 61 6e 64 20 6e 6f 74 20 69 74 file and not it
4940: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f s inode needs to
4950: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a be synced..** .
4960: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 ** The integer v
4970: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 alues to xLock()
4980: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 and xUnlock() a
4990: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 53 51 4c re one of.** SQL
49a0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 2c 20 53 ITE_LOCK_NONE, S
49b0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 41 44 2c QLITE_LOCK_READ,
49c0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 SQLITE_LOCK_RES
49d0: 45 52 56 45 44 2c 0a 2a 2a 20 53 51 4c 49 54 45 ERVED,.** SQLITE
49e0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 2c 20 6f _LOCK_PENDING, o
49f0: 72 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 r SQLITE_LOCK_EX
4a00: 43 4c 55 53 49 56 45 2e 20 20 78 4c 6f 63 6b 28 CLUSIVE. xLock(
4a10: 29 0a 2a 2a 20 69 6e 63 72 65 61 73 65 73 20 74 ).** increases t
4a20: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b he lock. xUnlock
4a30: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 () decreases the
4a40: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 20 54 68 65 20 lock. .** The
4a50: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f xCheckReservedLo
4a60: 63 6b 28 29 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b ck() method look
4a70: 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 s.** to see if a
4a80: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ny database conn
4a90: 65 63 74 69 6f 6e 2c 20 65 69 74 68 65 72 20 69 ection, either i
4aa0: 6e 20 74 68 69 73 0a 2a 2a 20 70 72 6f 63 65 73 n this.** proces
4ab0: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 s or in some oth
4ac0: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 er process, is h
4ad0: 6f 6c 64 69 6e 67 20 61 6e 20 52 45 53 45 52 56 olding an RESERV
4ae0: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 ED,.** PENDING,
4af0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 or EXCLUSIVE loc
4b00: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 k on the file.
4b10: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a It returns true.
4b20: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 ** if such a loc
4b30: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c k exists and fal
4b40: 73 65 20 69 66 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a se if not..** .*
4b50: 2a 20 78 42 72 65 61 6b 4c 6f 63 6b 28 29 20 61 * xBreakLock() a
4b60: 74 74 65 6d 70 74 73 20 74 6f 20 62 72 65 61 6b ttempts to break
4b70: 20 61 20 6c 6f 63 6b 20 68 65 6c 64 20 62 79 20 a lock held by
4b80: 61 6e 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2e another process.
4b90: 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 62 65 20 .** This can be
4ba0: 75 73 65 64 20 74 6f 20 72 65 6d 6f 76 65 20 61 used to remove a
4bb0: 20 73 74 61 6c 65 20 64 6f 74 2d 66 69 6c 65 20 stale dot-file
4bc0: 6c 6f 63 6b 2c 20 66 6f 72 20 65 78 61 6d 70 6c lock, for exampl
4bd0: 65 2e 0a 2a 2a 20 49 74 20 72 65 74 75 72 6e 73 e..** It returns
4be0: 20 30 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 0 on success an
4bf0: 64 20 6e 6f 6e 2d 7a 65 72 6f 20 66 6f 72 20 61 d non-zero for a
4c00: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 failure..**.**
4c10: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 The xSectorSize(
4c20: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 ) method returns
4c30: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 the sector size
4c40: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 of the.** devic
4c50: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 e that underlies
4c60: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 the file. The
4c70: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 sector size is t
4c80: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 he.** minimum wr
4c90: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 ite that can be
4ca0: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 performed withou
4cb0: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 t disturbing.**
4cc0: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 other bytes in t
4cd0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 he file. The xD
4ce0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 eviceCharacteris
4cf0: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 tics().** method
4d00: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 returns a bit v
4d10: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 ector describing
4d20: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 behaviors of th
4d30: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 e.** underlying
4d40: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 device:.**.** <u
4d50: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 l>.** <li> SQLIT
4d60: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 0a 2a E_IOCAP_ATOMIC.*
4d70: 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f * <li> SQLITE_IO
4d80: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 0a 2a 2a CAP_ATOMIC512.**
4d90: 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 <li> SQLITE_IOC
4da0: 41 50 5f 41 54 4f 4d 49 43 31 4b 0a 2a 2a 20 3c AP_ATOMIC1K.** <
4db0: 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 li> SQLITE_IOCAP
4dc0: 5f 41 54 4f 4d 49 43 32 4b 0a 2a 2a 20 3c 6c 69 _ATOMIC2K.** <li
4dd0: 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 > SQLITE_IOCAP_A
4de0: 54 4f 4d 49 43 34 4b 0a 2a 2a 20 3c 6c 69 3e 20 TOMIC4K.** <li>
4df0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
4e00: 4d 49 43 38 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 MIC8K.** <li> SQ
4e10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
4e20: 43 31 36 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c C16K.** <li> SQL
4e30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
4e40: 33 32 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 32K.** <li> SQLI
4e50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 TE_IOCAP_ATOMIC6
4e60: 34 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 4K.** <li> SQLIT
4e70: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 E_IOCAP_SAFE_APP
4e80: 45 4e 44 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 END.** <li> SQLI
4e90: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
4ea0: 49 41 4c 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a IAL.** </ul>.**.
4eb0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f ** The SQLITE_IO
4ec0: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 CAP_ATOMIC prope
4ed0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 rty means that a
4ee0: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 ll writes of.**
4ef0: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f any size are ato
4f00: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 mic. The SQLITE
4f10: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e _IOCAP_ATOMICnnn
4f20: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 values.** mean
4f30: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 that writes of b
4f40: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e locks that are n
4f50: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 nn bytes in size
4f60: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 and.** are alig
4f70: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 ned to an addres
4f80: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e s which is an in
4f90: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f teger multiple o
4fa0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f f.** nnn are ato
4fb0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 mic. The SQLITE
4fc0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
4fd0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a ND value means.*
4fe0: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 * that when data
4ff0: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 is appended to
5000: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 a file, the data
5010: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 is appended.**
5020: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 first then the s
5030: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 ize of the file
5040: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 is extended, nev
5050: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 er the other.**
5060: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 way around. The
5070: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
5080: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 QUENTIAL propert
5090: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 y means that.**
50a0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 information is w
50b0: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 ritten to disk i
50c0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 n the same order
50d0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 as calls.** to
50e0: 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 74 79 70 xWrite()..*/.typ
50f0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
5100: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 te3_io_methods s
5110: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
5120: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 s;.struct sqlite
5130: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 3_io_methods {.
5140: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 int iVersion;.
5150: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 int (*xClose)(s
5160: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
5170: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 int (*xRead)(sq
5180: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 lite3_file*, voi
5190: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 d*, int iAmt, sq
51a0: 6c 69 74 65 5f 69 6e 74 36 34 20 69 4f 66 73 74 lite_int64 iOfst
51b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 );. int (*xWrit
51c0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
51d0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
51e0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 5f nt iAmt, sqlite_
51f0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 int64 iOfst);.
5200: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 int (*xTruncate)
5210: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
5220: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 69 7a sqlite_int64 siz
5230: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e e);. int (*xSyn
5240: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a c)(sqlite3_file*
5250: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 , int flags);.
5260: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 int (*xFileSize)
5270: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
5280: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 2a 70 53 sqlite_int64 *pS
5290: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c ize);. int (*xL
52a0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ock)(sqlite3_fil
52b0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 e*, int);. int
52c0: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 (*xUnlock)(sqlit
52d0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a e3_file*, int);.
52e0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 int (*xCheckRe
52f0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 servedLock)(sqli
5300: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e te3_file*);. in
5310: 74 20 28 2a 78 42 72 65 61 6b 4c 6f 63 6b 29 28 t (*xBreakLock)(
5320: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a sqlite3_file*);.
5330: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 53 74 61 int (*xLockSta
5340: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 te)(sqlite3_file
5350: 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 *);. int (*xSe
5360: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 ctorSize)(sqlite
5370: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 3_file*);. int
5380: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 (*xDeviceCharact
5390: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 eristics)(sqlite
53a0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 3_file*);. /* A
53b0: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 dditional method
53c0: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
53d0: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
53e0: 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 s */.};../*.** C
53f0: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 API3REF: Mutex H
5400: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 andle.**.** The
5410: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 mutex module wit
5420: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e hin SQLite defin
5430: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 es [sqlite3_mute
5440: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 x] to be an.** a
5450: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 bstract type for
5460: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e a mutex object.
5470: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 The SQLite cor
5480: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a e never looks.**
5490: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c at the internal
54a0: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
54b0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d of an [sqlite3_m
54c0: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a utex]. It only.
54d0: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f ** deals with po
54e0: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 inters to the [s
54f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 qlite3_mutex] ob
5500: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 ject..**.** Mute
5510: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 xes are created
5520: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d using [sqlite3_m
5530: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a utex_alloc()]..*
5540: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
5550: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 sqlite3_mutex s
5560: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f qlite3_mutex;../
5570: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
5580: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 S Interface Obje
5590: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 ct.**.** An inst
55a0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
55b0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 ect defines the
55c0: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 interface betwee
55d0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 n the.** SQLite
55e0: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 core and the und
55f0: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e erlying operatin
5600: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 g system. The "
5610: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e vfs".** in the n
5620: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 ame of the objec
5630: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 t stands for "vi
5640: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 rtual file syste
5650: 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 56 m"..**.** The iV
5660: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 ersion field is
5670: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 initially 1 but
5680: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 66 6f may be larger fo
5690: 72 20 66 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 r future.** vers
56a0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 ions of SQLite.
56b0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c Additional fiel
56c0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 ds may be append
56d0: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 ed to this.** ob
56e0: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 ject when the iV
56f0: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 ersion value is
5700: 69 6e 63 72 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a increased..**.**
5710: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 The szOsFile fi
5720: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 eld is the size
5730: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 of the subclasse
5740: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 0a 2a d sqlite3_file.*
5750: 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 * structure used
5760: 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d by this VFS. m
5770: 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 xPathname is the
5780: 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 maximum length
5790: 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 of.** a pathname
57a0: 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a in this VFS..**
57b0: 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 76 .** Registered v
57c0: 66 73 20 6d 6f 64 75 6c 65 73 20 61 72 65 20 6b fs modules are k
57d0: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 ept on a linked
57e0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a list formed by.*
57f0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e * the pNext poin
5800: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ter. The [sqlit
5810: 65 33 5f 72 65 67 69 73 74 65 72 5f 76 66 73 28 e3_register_vfs(
5820: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 )].** and [sqlit
5830: 65 33 5f 75 6e 72 65 67 69 73 74 65 72 5f 76 66 e3_unregister_vf
5840: 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 s()] interfaces
5850: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 manage this list
5860: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d .** in a thread-
5870: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b safe way. The [
5880: 73 71 6c 69 74 65 33 5f 66 69 6e 64 5f 76 66 73 sqlite3_find_vfs
5890: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a ()] interface.**
58a0: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 searches the li
58b0: 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e st..**.** The pN
58c0: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 ext field is the
58d0: 20 6f 6e 6c 79 20 66 69 65 6c 64 73 20 69 6e 20 only fields in
58e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 the sqlite3_vfs
58f0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 .** structure th
5900: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 at SQLite will e
5910: 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c ver modify. SQL
5920: 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 ite will only ac
5930: 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 cess.** or modif
5940: 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 y this field whi
5950: 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 le holding a par
5960: 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d ticular static m
5970: 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 utex..** The app
5980: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
5990: 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 never modify any
59a0: 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 thing within the
59b0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 sqlite3_vfs.**
59c0: 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 object once the
59d0: 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 object has been
59e0: 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a registered..**.*
59f0: 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c * The zName fiel
5a00: 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 d holds the name
5a10: 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 of the VFS modu
5a20: 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 le. The name mu
5a30: 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 st.** be unique
5a40: 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d across all VFS m
5a50: 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 odules..**.** SQ
5a60: 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e Lite will guaran
5a70: 74 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 69 tee that the zFi
5a80: 6c 65 6e 61 6d 65 20 73 74 72 69 6e 67 20 70 61 lename string pa
5a90: 73 73 65 64 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e ssed to.** xOpen
5aa0: 28 29 20 69 73 20 61 20 66 75 6c 6c 20 70 61 74 () is a full pat
5ab0: 68 6e 61 6d 65 20 61 73 20 67 65 6e 65 72 61 74 hname as generat
5ac0: 65 64 20 62 79 20 78 46 75 6c 6c 50 61 74 68 6e ed by xFullPathn
5ad0: 61 6d 65 28 29 20 61 6e 64 0a 2a 2a 20 74 68 61 ame() and.** tha
5ae0: 74 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c t the string wil
5af0: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 l be valid and u
5b00: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 nchanged until x
5b10: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 Close() is.** ca
5b20: 6c 6c 65 64 2e 20 20 53 6f 20 74 68 65 20 73 71 lled. So the sq
5b30: 6c 69 74 65 33 5f 66 69 6c 65 20 63 61 6e 20 73 lite3_file can s
5b40: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 tore a pointer t
5b50: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d o the.** filenam
5b60: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f e if it needs to
5b70: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 remember the fi
5b80: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 lename for some
5b90: 72 65 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 reason..**.** Th
5ba0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
5bb0: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 73 20 61 to xOpen() is a
5bc0: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6c 61 copy of the fla
5bd0: 67 73 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 gs argument.** t
5be0: 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
5bf0: 32 28 29 2e 20 20 49 66 20 73 71 6c 69 74 65 33 2(). If sqlite3
5c00: 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 _open() or sqlit
5c10: 65 33 5f 6f 70 65 6e 31 36 28 29 0a 2a 2a 20 69 e3_open16().** i
5c20: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 s used, then fla
5c30: 67 73 20 69 73 20 53 51 4c 49 54 45 5f 4f 50 45 gs is SQLITE_OPE
5c40: 4e 5f 52 45 41 44 57 52 49 54 45 20 7c 20 53 51 N_READWRITE | SQ
5c50: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
5c60: 2e 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 ..** If xOpen()
5c70: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 opens a file rea
5c80: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 d-only then it s
5c90: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 ets *pOutFlags t
5ca0: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 53 51 4c o.** include SQL
5cb0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
5cc0: 59 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 Y. Other bits i
5cd0: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 n *pOutFlags may
5ce0: 20 62 65 0a 2a 2a 20 73 65 74 2e 0a 2a 2a 20 0a be.** set..** .
5cf0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 ** SQLite will a
5d00: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 lso add one of t
5d10: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 he following fla
5d20: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 gs to the xOpen(
5d30: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e ).** call, depen
5d40: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 ding on the obje
5d50: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a ct being opened:
5d60: 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 .** .** <ul>.**
5d70: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
5d80: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c EN_MAIN_DB].** <
5d90: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
5da0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a N_MAIN_JOURNAL].
5db0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
5dc0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a _OPEN_TEMP_DB].*
5dd0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
5de0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
5df0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
5e00: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 ITE_OPEN_SUBJOUR
5e10: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
5e20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 QLITE_OPEN_MASTE
5e30: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f R_JOURNAL].** </
5e40: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 ul>.**.** The fi
5e50: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 le I/O implement
5e60: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 ation can use th
5e70: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c e object type fl
5e80: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 ags to.** change
5e90: 73 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 s the way it dea
5ea0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 ls with files.
5eb0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 For example, an
5ec0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 application.** t
5ed0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 hat does not car
5ee0: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 e about crash re
5ef0: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 covery or rollba
5f00: 63 6b 2c 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a ck, might make.*
5f10: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 * the open of a
5f20: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e journal file a n
5f30: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f o-op. Writes to
5f40: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 61 72 this journal ar
5f50: 65 0a 2a 2a 20 61 6c 73 6f 20 61 20 6e 6f 2d 6f e.** also a no-o
5f60: 70 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 p. Any attempt
5f70: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 to read the jour
5f80: 6e 61 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 nal return SQLIT
5f90: 45 5f 49 4f 45 52 52 2e 0a 2a 2a 20 4f 72 20 74 E_IOERR..** Or t
5fa0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
5fb0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a n might recogniz
5fc0: 65 20 74 68 65 20 61 20 64 61 74 61 62 61 73 65 e the a database
5fd0: 20 66 69 6c 65 20 77 69 6c 6c 0a 2a 2a 20 62 65 file will.** be
5fe0: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 doing page-alig
5ff0: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 ned sector reads
6000: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 and writes in a
6010: 20 72 61 6e 64 6f 6d 20 6f 72 64 65 72 0a 2a 2a random order.**
6020: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 and set up its
6030: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 I/O subsystem ac
6040: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a cordingly..** .*
6050: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 * SQLite might a
6060: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 lso add one of t
6070: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 he following fla
6080: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a gs to the xOpen.
6090: 2a 2a 20 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a ** method:.** .*
60a0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
60b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
60c0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c TEONCLOSE].** <l
60d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f i> [SQLITE_OPEN_
60e0: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f EXCLUSIVE].** </
60f0: 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 5b ul>.** .** The [
6100: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
6110: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 TEONCLOSE] flag
6120: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 means the file s
6130: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 hould be.** dele
6140: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 ted when it is c
6150: 6c 6f 73 65 64 2e 20 20 54 68 69 73 20 77 69 6c losed. This wil
6160: 6c 20 61 6c 77 61 79 73 20 62 65 20 73 65 74 20 l always be set
6170: 66 6f 72 20 54 45 4d 50 20 0a 2a 2a 20 64 61 74 for TEMP .** dat
6180: 61 62 61 73 65 73 20 61 6e 64 20 6a 6f 75 72 6e abases and journ
6190: 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a als and for subj
61a0: 6f 75 72 6e 61 6c 73 2e 20 20 54 68 65 20 0a 2a ournals. The .*
61b0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 * [SQLITE_OPEN_E
61c0: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d XCLUSIVE] flag m
61d0: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 eans the file sh
61e0: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a ould be opened.*
61f0: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 * for exclusive
6200: 61 63 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c access. This fl
6210: 61 67 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c ag is set for al
6220: 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a l files except.*
6230: 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 * for the main d
6240: 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a atabase file..**
6250: 20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 .** The sqlite3
6260: 5f 66 69 6c 65 20 73 74 72 75 63 74 75 72 65 20 _file structure
6270: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 passed as the th
6280: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ird argument to.
6290: 2a 2a 20 78 4f 70 65 6e 20 69 73 20 61 6c 6c 6f ** xOpen is allo
62a0: 63 61 74 65 64 20 62 79 20 74 68 65 20 63 61 6c cated by the cal
62b0: 6c 65 72 2e 20 20 78 4f 70 65 6e 20 6a 75 73 74 ler. xOpen just
62c0: 20 66 69 6c 6c 73 20 69 74 20 69 6e 2e 20 20 54 fills it in. T
62d0: 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 20 61 6c 6c he.** caller all
62e0: 6f 63 61 74 65 73 20 61 20 6d 69 6e 69 6d 75 6d ocates a minimum
62f0: 20 6f 66 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 of szOsFile byt
6300: 65 73 20 66 6f 72 20 74 68 65 20 73 71 6c 69 74 es for the sqlit
6310: 65 33 5f 66 69 6c 65 0a 2a 2a 20 73 74 72 75 63 e3_file.** struc
6320: 74 75 72 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 ture..** .** The
6330: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
6340: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 to xAccess() may
6350: 20 62 65 20 30 20 28 74 6f 20 74 65 73 74 20 66 be 0 (to test f
6360: 6f 72 20 74 68 65 0a 2a 2a 20 65 78 69 73 74 61 or the.** exista
6370: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 29 20 6f nce of a file) o
6380: 72 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f r SQLITE_ACCESS_
6390: 52 45 41 44 57 52 49 54 45 20 74 6f 20 74 65 73 READWRITE to tes
63a0: 74 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20 61 t to see.** if a
63b0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c file is readabl
63c0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 e and writable,
63d0: 6f 72 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 or SQLITE_ACCESS
63e0: 5f 52 45 41 44 4f 4e 4c 59 0a 2a 2a 20 74 6f 20 _READONLY.** to
63f0: 74 65 73 74 20 74 6f 20 73 65 65 20 69 66 20 61 test to see if a
6400: 20 66 69 6c 65 20 69 73 20 72 65 61 64 2d 6f 6e file is read-on
6410: 6c 79 2e 20 20 54 68 65 20 66 69 6c 65 20 63 61 ly. The file ca
6420: 6e 20 62 65 20 61 20 0a 2a 2a 20 64 69 72 65 63 n be a .** direc
6430: 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c tory..** .** SQL
6440: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 ite will always
6450: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 allocate at leas
6460: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 t mxPathname+1 b
6470: 79 74 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f yte for.** the o
6480: 75 74 70 75 74 20 62 75 66 66 65 72 73 20 66 6f utput buffers fo
6490: 72 20 78 47 65 74 54 65 6d 70 4e 61 6d 65 20 61 r xGetTempName a
64a0: 6e 64 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 nd xFullPathname
64b0: 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 52 61 ..** .** The xRa
64c0: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 ndomness(), xSle
64d0: 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 ep(), and xCurre
64e0: 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 ntTime() interfa
64f0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 ces.** are not s
6500: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f trictly a part o
6510: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d f the filesystem
6520: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a , but they are.*
6530: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 * included in th
6540: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 e VFS structure
6550: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 for completeness
6560: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d ..** The xRandom
6570: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 ness() function
6580: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 attempts to retu
6590: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a rn nBytes bytes.
65a0: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 ** of good-quali
65b0: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e ty randomness in
65c0: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 to zOut. The re
65d0: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a turn value is.**
65e0: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 the actual numb
65f0: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 er of bytes of r
6600: 61 6e 64 6f 6d 6e 65 73 73 20 67 65 6e 65 72 61 andomness genera
6610: 74 65 64 2e 20 20 54 68 65 0a 2a 2a 20 78 53 6c ted. The.** xSl
6620: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 eep() method cau
6630: 73 65 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 se the calling t
6640: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 hread to sleep f
6650: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 or at.** least t
6660: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 he number of mic
6670: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e roseconds given.
6680: 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 The xCurrentTi
6690: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 me().** method r
66a0: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 eturns a Julian
66b0: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 Day Number for t
66c0: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 he current date
66d0: 61 6e 64 0a 2a 2a 20 74 69 6d 65 2e 0a 2a 2f 0a and.** time..*/.
66e0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
66f0: 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 qlite3_vfs sqlit
6700: 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 e3_vfs;.struct s
6710: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 qlite3_vfs {. i
6720: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 nt iVersion;
6730: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 /* Struc
6740: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d ture version num
6750: 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f ber */. int szO
6760: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 sFile;
6770: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 /* Size of sub
6780: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f classed sqlite3_
6790: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 file */. int mx
67a0: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 Pathname;
67b0: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 /* Maximum fi
67c0: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 le pathname leng
67d0: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f th */. sqlite3_
67e0: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 vfs *pNext;
67f0: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 /* Next registe
6800: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e red VFS */. con
6810: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 st char *zName;
6820: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 /* Name of
6830: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 this virtual fi
6840: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 le system */. v
6850: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 oid *pAppData;
6860: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 /* Point
6870: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f er to applicatio
6880: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 n-specific data
6890: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e */. int (*xOpen
68a0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
68b0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
68c0: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e, sqlite3_file*
68d0: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
68e0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 int flags, int
68f0: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 *pOutFlags);. i
6900: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 nt (*xDelete)(sq
6910: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
6920: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 t char *zName, i
6930: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 nt syncDir);. i
6940: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 nt (*xAccess)(sq
6950: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
6960: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 t char *zName, i
6970: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 nt flags);. int
6980: 20 28 2a 78 47 65 74 54 65 6d 70 4e 61 6d 65 29 (*xGetTempName)
6990: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
69a0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e har *zOut);. in
69b0: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d t (*xFullPathnam
69c0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
69d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
69e0: 6d 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b me, char *zOut);
69f0: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 . void *(*xDlOp
6a00: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a en)(sqlite3_vfs*
6a10: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 , const char *zF
6a20: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 ilename);. void
6a30: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c (*xDlError)(sql
6a40: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e ite3_vfs*, int n
6a50: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 Byte, char *zErr
6a60: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a Msg);. void *(*
6a70: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f xDlSym)(sqlite3_
6a80: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 vfs*,void*, cons
6a90: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 t char *zSymbol)
6aa0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c ;. void (*xDlCl
6ab0: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ose)(sqlite3_vfs
6ac0: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 *, void*);. int
6ad0: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 (*xRandomness)(
6ae0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
6af0: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a t nByte, char *z
6b00: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 Out);. int (*xS
6b10: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 leep)(sqlite3_vf
6b20: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 s*, int microsec
6b30: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 onds);. int (*x
6b40: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c CurrentTime)(sql
6b50: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c ite3_vfs*, doubl
6b60: 65 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 e*);. /* New fi
6b70: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 elds may be appe
6b80: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 nded in figure v
6b90: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 ersions. The iV
6ba0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 ersion. ** valu
6bb0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 e will increment
6bc0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 whenever this h
6bd0: 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 23 appens. */.};..#
6be0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
6bf0: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 CESS_EXISTS 0
6c00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6c10: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
6c20: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
6c30: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 4f 4e 4c E_ACCESS_READONL
6c40: 59 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 Y 2../*.** CAPI
6c50: 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 3REF: Enable Or
6c60: 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 Disable Extended
6c70: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a Result Codes.**
6c80: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
6c90: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
6ca0: 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c bles the.** [SQL
6cb0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c ITE_IOERR_READ |
6cc0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
6cd0: 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 2e codes] feature.
6ce0: 0a 2a 2a 20 42 79 20 64 65 66 61 75 6c 74 2c 20 .** By default,
6cf0: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 SQLite API routi
6d00: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f nes return one o
6d10: 66 20 6f 6e 6c 79 20 32 36 20 69 6e 74 65 67 65 f only 26 intege
6d20: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 r.** [SQLITE_OK
6d30: 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e | result codes].
6d40: 20 20 57 68 65 6e 20 65 78 74 65 6e 64 65 64 20 When extended
6d50: 72 65 73 75 6c 74 20 63 6f 64 65 73 0a 2a 2a 20 result codes.**
6d60: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 74 are enabled by t
6d70: 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 65 his routine, the
6d80: 20 72 65 70 65 74 6f 69 72 65 20 6f 66 20 72 65 repetoire of re
6d90: 73 75 6c 74 20 63 6f 64 65 73 20 63 61 6e 20 62 sult codes can b
6da0: 65 0a 2a 2a 20 6d 75 63 68 20 6c 61 72 67 65 72 e.** much larger
6db0: 20 61 6e 64 20 63 61 6e 20 28 68 6f 70 65 66 75 and can (hopefu
6dc0: 6c 6c 79 29 20 70 72 6f 76 69 64 65 20 6d 6f 72 lly) provide mor
6dd0: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 e detailed infor
6de0: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 mation.** about
6df0: 74 68 65 20 63 61 75 73 65 20 6f 66 20 61 6e 20 the cause of an
6e00: 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 error..**.** The
6e10: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
6e20: 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 76 61 is a boolean va
6e30: 6c 75 65 20 74 68 61 74 20 74 75 72 6e 73 20 65 lue that turns e
6e40: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a xtended result.*
6e50: 2a 20 63 6f 64 65 73 20 6f 6e 20 61 6e 64 20 6f * codes on and o
6e60: 66 66 2e 20 20 45 78 74 65 6e 64 65 64 20 72 65 ff. Extended re
6e70: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6f sult codes are o
6e80: 66 66 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f ff by default fo
6e90: 72 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 r.** backwards c
6ea0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 ompatibility wit
6eb0: 68 20 6f 6c 64 65 72 20 76 65 72 73 69 6f 6e 73 h older versions
6ec0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 of SQLite..*/.i
6ed0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e nt sqlite3_exten
6ee0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 ded_result_codes
6ef0: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f (sqlite3*, int o
6f00: 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 noff);../*.** CA
6f10: 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 PI3REF: Last Ins
6f20: 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 ert Rowid.**.**
6f30: 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e Each entry in an
6f40: 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 SQLite table ha
6f50: 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 s a unique 64-bi
6f60: 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 t signed integer
6f70: 20 6b 65 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 74 key.** called t
6f80: 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65 20 he "rowid". The
6f90: 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 rowid is always
6fa0: 61 76 61 69 6c 61 62 6c 65 20 61 73 20 61 6e 20 available as an
6fb0: 75 6e 64 65 63 6c 61 72 65 64 0a 2a 2a 20 63 6f undeclared.** co
6fc0: 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 lumn named ROWID
6fd0: 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 , OID, or _ROWID
6fe0: 5f 2e 20 20 49 66 20 74 68 65 20 74 61 62 6c 65 _. If the table
6ff0: 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 has a column of
7000: 0a 2a 2a 20 74 79 70 65 20 49 4e 54 45 47 45 52 .** type INTEGER
7010: 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74 68 65 PRIMARY KEY the
7020: 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 n that column is
7030: 20 61 6e 6f 74 68 65 72 20 61 6e 20 61 6c 69 61 another an alia
7040: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 72 6f 77 s for the.** row
7050: 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 id..**.** This r
7060: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
7070: 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 he rowid of the
7080: 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 most recent INSE
7090: 52 54 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 64 RT into.** the d
70a0: 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 atabase from the
70b0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
70c0: 74 69 6f 6e 20 67 69 76 65 6e 20 69 6e 20 74 68 tion given in th
70d0: 65 20 66 69 72 73 74 20 0a 2a 2a 20 61 72 67 75 e first .** argu
70e0: 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 69 6e 73 ment. If no ins
70f0: 65 72 74 73 20 68 61 76 65 20 65 76 65 72 20 6f erts have ever o
7100: 63 63 75 72 72 65 64 20 6f 6e 20 74 68 69 73 20 ccurred on this
7110: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
7120: 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 ection, zero is
7130: 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
7140: 49 66 20 61 6e 20 49 4e 53 45 52 54 20 6f 63 63 If an INSERT occ
7150: 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 urs within a tri
7160: 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 gger, then the r
7170: 6f 77 69 64 20 6f 66 20 74 68 65 0a 2a 2a 20 69 owid of the.** i
7180: 6e 73 65 72 74 65 64 20 72 6f 77 20 69 73 20 72 nserted row is r
7190: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 eturned by this
71a0: 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 routine as long
71b0: 61 73 20 74 68 65 20 74 72 69 67 67 65 72 0a 2a as the trigger.*
71c0: 2a 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 42 * is running. B
71d0: 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 ut once the trig
71e0: 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 ger terminates,
71f0: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
7200: 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f ed.** by this ro
7210: 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f utine reverts to
7220: 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 the last value
7230: 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 inserted before
7240: 74 68 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 66 the.** trigger f
7250: 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 ired..**.** If a
7260: 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 64 6f nother thread do
7270: 65 73 20 61 20 6e 65 77 20 69 6e 73 65 72 74 20 es a new insert
7280: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 on the same data
7290: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
72a0: 2a 2a 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f ** while this ro
72b0: 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 utine is running
72c0: 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 and thus change
72d0: 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 s the last inser
72e0: 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 74 68 65 6e t rowid,.** then
72f0: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
7300: 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e e of this routin
7310: 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a e is undefined..
7320: 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 */.sqlite3_int64
7330: 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e sqlite3_last_in
7340: 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 sert_rowid(sqlit
7350: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
7360: 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 I3REF: Count The
7370: 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 Number Of Rows
7380: 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 54 Modified.**.** T
7390: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 his function ret
73a0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
73b0: 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 of database rows
73c0: 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 that were chang
73d0: 65 64 0a 2a 2a 20 28 6f 72 20 69 6e 73 65 72 74 ed.** (or insert
73e0: 65 64 20 6f 72 20 64 65 6c 65 74 65 64 29 20 62 ed or deleted) b
73f0: 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e y the most recen
7400: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e t SQL statement.
7410: 20 20 4f 6e 6c 79 0a 2a 2a 20 63 68 61 6e 67 65 Only.** change
7420: 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 s that are direc
7430: 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 tly specified by
7440: 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 the INSERT, UPD
7450: 41 54 45 2c 20 6f 72 0a 2a 2a 20 44 45 4c 45 54 ATE, or.** DELET
7460: 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 E statement are
7470: 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 counted. Auxili
7480: 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 ary changes caus
7490: 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 ed by.** trigger
74a0: 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 s are not counte
74b0: 64 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71 6c d. Use the [sql
74c0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
74d0: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a es()] function.*
74e0: 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f * to find the to
74f0: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 tal number of ch
7500: 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 anges including
7510: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 changes caused b
7520: 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a y triggers..**.*
7530: 2a 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 * Within the bod
7540: 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 20 y of a trigger,
7550: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e the sqlite3_chan
7560: 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 ges() interface
7570: 63 61 6e 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 can be.** called
7580: 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d to find the num
7590: 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 ber of.** change
75a0: 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 s in the most re
75b0: 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 cently completed
75c0: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
75d0: 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 or DELETE.** st
75e0: 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 atement within t
75f0: 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 74 he body of the t
7600: 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 6c rigger..**.** Al
7610: 6c 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f l changes are co
7620: 75 6e 74 65 64 2c 20 65 76 65 6e 20 69 66 20 74 unted, even if t
7630: 68 65 79 20 77 65 72 65 20 6c 61 74 65 72 20 75 hey were later u
7640: 6e 64 6f 6e 65 20 62 79 20 61 0a 2a 2a 20 52 4f ndone by a.** RO
7650: 4c 4c 42 41 43 4b 20 6f 72 20 41 42 4f 52 54 2e LLBACK or ABORT.
7660: 20 20 45 78 63 65 70 74 2c 20 63 68 61 6e 67 65 Except, change
7670: 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 s associated wit
7680: 68 20 63 72 65 61 74 69 6e 67 20 61 6e 64 0a 2a h creating and.*
7690: 2a 20 64 72 6f 70 70 69 6e 67 20 74 61 62 6c 65 * dropping table
76a0: 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 s are not counte
76b0: 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 61 d..**.** If a ca
76c0: 6c 6c 62 61 63 6b 20 69 6e 76 6f 6b 65 73 20 5b llback invokes [
76d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
76e0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 or [sqlite3_step
76f0: 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 2c ()] recursively,
7700: 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 68 61 .** then the cha
7710: 6e 67 65 73 20 69 6e 20 74 68 65 20 69 6e 6e 65 nges in the inne
7720: 72 2c 20 72 65 63 75 72 73 69 76 65 20 63 61 6c r, recursive cal
7730: 6c 20 61 72 65 20 63 6f 75 6e 74 65 64 20 74 6f l are counted to
7740: 67 65 74 68 65 72 0a 2a 2a 20 77 69 74 68 20 74 gether.** with t
7750: 68 65 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 he changes in th
7760: 65 20 6f 75 74 65 72 20 63 61 6c 6c 2e 0a 2a 2a e outer call..**
7770: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 .** SQLite imple
7780: 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e ments the comman
7790: 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 d "DELETE FROM t
77a0: 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 able" without a
77b0: 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 WHERE clause.**
77c0: 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 by dropping and
77d0: 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 recreating the t
77e0: 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 able. (This is
77f0: 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e much faster than
7800: 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 going.** throug
7810: 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 h and deleting i
7820: 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e ndividual elemen
7830: 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c ts from the tabl
7840: 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 0a e.) Because of.
7850: 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 ** this optimiza
7860: 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67 65 tion, the change
7870: 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c 45 count for "DELE
7880: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 TE FROM table" w
7890: 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 ill be.** zero r
78a0: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 egardless of the
78b0: 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 number of eleme
78c0: 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 nts that were or
78d0: 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a iginally in the.
78e0: 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67 65 74 ** table. To get
78f0: 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 an accurate cou
7900: 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 nt of the number
7910: 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 of rows deleted
7920: 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 , use.** "DELETE
7930: 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 FROM table WHER
7940: 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a E 1" instead..**
7950: 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 .** If another t
7960: 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e hread makes chan
7970: 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 ges on the same
7980: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
7990: 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 68 69 ion.** while thi
79a0: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e s routine is run
79b0: 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 72 65 ning then the re
79c0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
79d0: 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 is routine.** is
79e0: 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 undefined..*/.i
79f0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 nt sqlite3_chang
7a00: 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
7a10: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
7a20: 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 otal Number Of R
7a30: 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 2a ows Modified.***
7a40: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
7a50: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
7a60: 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 mber of database
7a70: 20 72 6f 77 73 20 74 68 61 74 20 68 61 76 65 20 rows that have
7a80: 62 65 65 6e 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 been.** modified
7a90: 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41 by INSERT, UPDA
7aa0: 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 TE or DELETE sta
7ab0: 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 tements since th
7ac0: 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c e database handl
7ad0: 65 0a 2a 2a 20 77 61 73 20 6f 70 65 6e 65 64 2e e.** was opened.
7ae0: 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 55 This includes U
7af0: 50 44 41 54 45 2c 20 49 4e 53 45 52 54 20 61 6e PDATE, INSERT an
7b00: 64 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 d DELETE stateme
7b10: 6e 74 73 20 65 78 65 63 75 74 65 64 0a 2a 2a 20 nts executed.**
7b20: 61 73 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 as part of trigg
7b30: 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 41 6c 6c er programs. All
7b40: 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 changes are cou
7b50: 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 nted as soon as
7b60: 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 the.** statement
7b70: 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d that makes them
7b80: 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 is completed (w
7b90: 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e hen the statemen
7ba0: 74 20 68 61 6e 64 6c 65 20 69 73 0a 2a 2a 20 70 t handle is.** p
7bb0: 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 assed to [sqlite
7bc0: 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
7bd0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 73 65 28 qlite3_finalise(
7be0: 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 )])..**.** See a
7bf0: 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
7c00: 5f 63 68 61 6e 67 65 28 29 5d 20 69 6e 74 65 72 _change()] inter
7c10: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 face..**.** SQLi
7c20: 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 te implements th
7c30: 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 e command "DELET
7c40: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 E FROM table" wi
7c50: 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c thout a WHERE cl
7c60: 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 ause.** by dropp
7c70: 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 ing and recreati
7c80: 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 ng the table. (
7c90: 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 This is much fas
7ca0: 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a ter than going.*
7cb0: 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 * through and de
7cc0: 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 leting individua
7cd0: 6c 20 65 6c 65 6d 65 6e 74 73 20 66 6f 72 6d 20 l elements form
7ce0: 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 the table.) Bec
7cf0: 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20 ause of.** this
7d00: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 optimization, th
7d10: 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 20 66 e change count f
7d20: 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 or "DELETE FROM
7d30: 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a table" will be.*
7d40: 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 73 * zero regardles
7d50: 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 s of the number
7d60: 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 of elements that
7d70: 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 were originally
7d80: 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 in the.** table
7d90: 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 . To get an accu
7da0: 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 rate count of th
7db0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 e number of rows
7dc0: 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a deleted, use.**
7dd0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 "DELETE FROM ta
7de0: 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 ble WHERE 1" ins
7df0: 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 tead..**.** If a
7e00: 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 6d 61 nother thread ma
7e10: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 kes changes on t
7e20: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
7e30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 connection.** w
7e40: 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e hile this routin
7e50: 65 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 e is running the
7e60: 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c n the return val
7e70: 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 ue of this routi
7e80: 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e ne.** is undefin
7e90: 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ed..*/.int sqlit
7ea0: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
7eb0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
7ec0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 ** CAPI3REF: Int
7ed0: 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 errupt A Long-Ru
7ee0: 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a nning Query.**.*
7ef0: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
7f00: 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 causes any pendi
7f10: 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 ng database oper
7f20: 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 ation to abort a
7f30: 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 nd.** return at
7f40: 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 its earliest opp
7f50: 6f 72 74 75 6e 69 74 79 2e 20 20 54 68 69 73 20 ortunity. This
7f60: 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 routine is typic
7f70: 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 ally.** called i
7f80: 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 n response to a
7f90: 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 user action such
7fa0: 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 as pressing "Ca
7fb0: 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c ncel".** or Ctrl
7fc0: 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 -C where the use
7fd0: 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 r wants a long q
7fe0: 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 uery operation t
7ff0: 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 o halt.** immedi
8000: 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 ately..**.** It
8010: 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 is safe to call
8020: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f this routine fro
8030: 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 m a thread diffe
8040: 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a rent from the.**
8050: 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 thread that is
8060: 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e currently runnin
8070: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f g the database o
8080: 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 peration. But i
8090: 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 t.** is not safe
80a0: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f to call this ro
80b0: 75 74 69 6e 65 20 77 69 74 68 20 61 20 64 61 74 utine with a dat
80c0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
80d0: 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 that.** is clos
80e0: 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 ed or might clos
80f0: 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 e before sqlite3
8100: 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 _interrupt() ret
8110: 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 urns..**.** The
8120: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 SQL operation th
8130: 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 at is interrupte
8140: 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 d will return [S
8150: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d QLITE_INTERRUPT]
8160: 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 ..** If an inter
8170: 72 75 70 74 65 64 20 6f 70 65 72 61 74 69 6f 6e rupted operation
8180: 20 77 61 73 20 61 6e 20 75 70 64 61 74 65 20 74 was an update t
8190: 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e hat is inside an
81a0: 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 .** explicit tra
81b0: 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 nsaction, then t
81c0: 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 he entire transa
81d0: 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 72 6f ction will be ro
81e0: 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 61 75 74 lled.** back aut
81f0: 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2f 0a 76 omatically..*/.v
8200: 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 oid sqlite3_inte
8210: 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b rrupt(sqlite3*);
8220: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
8230: 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 : Determine If A
8240: 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 n SQL Statement
8250: 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a Is Complete.**.*
8260: 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e * These function
8270: 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 s return true if
8280: 20 74 68 65 20 67 69 76 65 6e 20 69 6e 70 75 74 the given input
8290: 20 73 74 72 69 6e 67 20 63 6f 6d 70 72 69 73 65 string comprise
82a0: 73 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 s.** one or more
82b0: 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 complete SQL st
82c0: 61 74 65 6d 65 6e 74 73 2e 20 46 6f 72 20 74 68 atements. For th
82d0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 e sqlite3_comple
82e0: 74 65 28 29 20 63 61 6c 6c 2c 0a 2a 2a 20 74 68 te() call,.** th
82f0: 65 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 e parameter must
8300: 20 62 65 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e be a nul-termin
8310: 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e ated UTF-8 strin
8320: 67 2e 20 46 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 g. For.** sqlite
8330: 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2c 20 3_complete16(),
8340: 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 a nul-terminated
8350: 20 6d 61 63 68 69 6e 65 20 62 79 74 65 20 6f 72 machine byte or
8360: 64 65 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e der UTF-16 strin
8370: 67 0a 2a 2a 20 69 73 20 72 65 71 75 69 72 65 64 g.** is required
8380: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
8390: 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 utines are usefu
83a0: 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 l for command-li
83b0: 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 ne input to dete
83c0: 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 rmine if the.**
83d0: 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 currently entere
83e0: 64 20 74 65 78 74 20 66 6f 72 6d 73 20 6f 6e 65 d text forms one
83f0: 20 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 6c 65 74 or more complet
8400: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
8410: 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 or.** if additi
8420: 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 onal input is ne
8430: 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 eded before send
8440: 69 6e 67 20 74 68 65 20 73 74 61 74 65 6d 65 6e ing the statemen
8450: 74 73 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 ts into.** SQLit
8460: 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 54 e for parsing. T
8470: 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 69 73 20 he algorithm is
8480: 73 69 6d 70 6c 65 2e 20 20 49 66 20 74 68 65 20 simple. If the
8490: 0a 2a 2a 20 6c 61 73 74 20 74 6f 6b 65 6e 20 6f .** last token o
84a0: 74 68 65 72 20 74 68 61 6e 20 73 70 61 63 65 73 ther than spaces
84b0: 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 69 73 and comments is
84c0: 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2c 20 74 68 a semicolon, th
84d0: 65 6e 20 72 65 74 75 72 6e 20 0a 2a 2a 20 74 72 en return .** tr
84e0: 75 65 2e 20 20 41 63 74 75 61 6c 6c 79 2c 20 74 ue. Actually, t
84f0: 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 69 73 20 he algorithm is
8500: 61 20 6c 69 74 74 6c 65 20 6d 6f 72 65 20 63 6f a little more co
8510: 6d 70 6c 69 63 61 74 65 64 20 74 68 61 6e 20 74 mplicated than t
8520: 68 61 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 hat.** in order
8530: 74 6f 20 64 65 61 6c 20 77 69 74 68 20 74 72 69 to deal with tri
8540: 67 67 65 72 73 2c 20 62 75 74 20 74 68 65 20 62 ggers, but the b
8550: 61 73 69 63 20 69 64 65 61 20 69 73 20 74 68 65 asic idea is the
8560: 20 73 61 6d 65 3a 20 20 74 68 65 0a 2a 2a 20 73 same: the.** s
8570: 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 tatement is not
8580: 63 6f 6d 70 6c 65 74 65 20 75 6e 6c 65 73 73 20 complete unless
8590: 69 74 20 65 6e 64 73 20 69 6e 20 61 20 73 65 6d it ends in a sem
85a0: 69 63 6f 6c 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 icolon..*/.int s
85b0: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 qlite3_complete(
85c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 const char *sql)
85d0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f ;.int sqlite3_co
85e0: 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 mplete16(const v
85f0: 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a oid *sql);../*.*
8600: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 * CAPI3REF: Regi
8610: 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 ster A Callback
8620: 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 To Handle SQLITE
8630: 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a _BUSY Errors.**.
8640: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
8650: 69 64 65 6e 74 69 66 69 65 73 20 61 20 63 61 6c identifies a cal
8660: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 lback function t
8670: 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 hat might be inv
8680: 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76 65 72 oked.** whenever
8690: 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d an attempt is m
86a0: 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 ade to open a da
86b0: 74 61 62 61 73 65 20 74 61 62 6c 65 20 0a 2a 2a tabase table .**
86c0: 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 that another th
86d0: 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73 73 20 read or process
86e0: 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 49 has locked..** I
86f0: 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 f the busy callb
8700: 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 ack is NULL, the
8710: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a n [SQLITE_BUSY].
8720: 2a 2a 20 28 6f 72 20 73 6f 6d 65 74 69 6d 65 73 ** (or sometimes
8730: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
8740: 4c 4f 43 4b 45 44 5d 29 0a 2a 2a 20 69 73 20 72 LOCKED]).** is r
8750: 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 eturned immediat
8760: 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 ely upon encount
8770: 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 0a ering the lock..
8780: 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63 ** If the busy c
8790: 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 4e allback is not N
87a0: 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a ULL, then the.**
87b0: 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 callback will b
87c0: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 e invoked with t
87d0: 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 wo arguments. T
87e0: 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75 he.** first argu
87f0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64 ment to the hand
8800: 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ler is a copy of
8810: 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 the void* point
8820: 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 er which.** is t
8830: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
8840: 74 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e t to this routin
8850: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 e. The second a
8860: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 rgument to.** th
8870: 65 20 68 61 6e 64 6c 65 72 20 69 73 20 74 68 65 e handler is the
8880: 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 number of times
8890: 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 that the busy h
88a0: 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 andler has.** be
88b0: 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 en invoked for t
88c0: 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e his locking even
88d0: 74 2e 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 t. If the.** bus
88e0: 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 y callback retur
88f0: 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 ns 0, then no ad
8900: 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 ditional attempt
8910: 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a s are made to.**
8920: 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 access the data
8930: 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 base and [SQLITE
8940: 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 _BUSY] or [SQLIT
8950: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
8960: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
8970: 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b If the callback
8980: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
8990: 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 o, then another
89a0: 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 attempt is made
89b0: 74 6f 20 6f 70 65 6e 20 74 68 65 0a 2a 2a 20 64 to open the.** d
89c0: 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 atabase for read
89d0: 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c ing and the cycl
89e0: 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a e repeats..**.**
89f0: 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 The presence of
8a00: 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 a busy handler
8a10: 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 does not guarant
8a20: 65 65 20 74 68 61 74 0a 2a 2a 20 69 74 20 77 69 ee that.** it wi
8a30: 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 ll be invoked wh
8a40: 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b en there is lock
8a50: 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 0a 2a 2a 20 contention..**
8a60: 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d If SQLite determ
8a70: 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 ines that invoki
8a80: 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ng the busy hand
8a90: 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 ler could result
8aa0: 20 69 6e 0a 2a 2a 20 61 20 64 65 61 64 6c 6f 63 in.** a deadloc
8ab0: 6b 2c 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 k, it will retur
8ac0: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 n [SQLITE_BUSY]
8ad0: 69 6e 73 74 65 61 64 2e 0a 2a 2a 20 43 6f 6e 73 instead..** Cons
8ae0: 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 ider a scenario
8af0: 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 where one proces
8b00: 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 s is holding a r
8b10: 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a ead lock that.**
8b20: 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f it is trying to
8b30: 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 promote to a re
8b40: 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a served lock and.
8b50: 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 ** a second proc
8b60: 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 ess is holding a
8b70: 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 reserved lock t
8b80: 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 hat it is trying
8b90: 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 .** to promote t
8ba0: 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c o an exclusive l
8bb0: 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 ock. The first
8bc0: 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 process cannot p
8bd0: 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 roceed.** becaus
8be0: 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 e it is blocked
8bf0: 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e by the second an
8c00: 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f d the second pro
8c10: 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 cess cannot.** p
8c20: 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 roceed because i
8c30: 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 t is blocked by
8c40: 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 the first. If b
8c50: 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a oth processes.**
8c60: 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 invoke the busy
8c70: 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 handlers, neith
8c80: 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 er will make any
8c90: 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 progress. Ther
8ca0: 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 efore,.** SQLite
8cb0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
8cc0: 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 _BUSY] for the f
8cd0: 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f irst process, ho
8ce0: 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a ping that this.*
8cf0: 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 * will induce th
8d00: 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 e first process
8d10: 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 to release its r
8d20: 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c ead lock and all
8d30: 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 ow.** the second
8d40: 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 process to proc
8d50: 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 eed..**.** The d
8d60: 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c efault busy call
8d70: 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a back is NULL..**
8d80: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
8d90: 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 BUSY] error is c
8da0: 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c onverted to [SQL
8db0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 ITE_IOERR_BLOCKE
8dc0: 44 5d 20 77 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 D] when.** SQLit
8dd0: 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 e is in the midd
8de0: 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 le of a large tr
8df0: 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 ansaction where
8e00: 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 all the.** chang
8e10: 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 es will not fit
8e20: 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f into the in-memo
8e30: 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 ry cache. SQLit
8e40: 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 e will.** alread
8e50: 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 y hold a RESERVE
8e60: 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 D lock on the da
8e70: 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 tabase file, but
8e80: 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 it needs.** to
8e90: 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 promote this loc
8ea0: 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 k to EXCLUSIVE s
8eb0: 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 o that it can sp
8ec0: 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 ill cache.** pag
8ed0: 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 es into the data
8ee0: 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 base file withou
8ef0: 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 t harm to concur
8f00: 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e rent.** readers.
8f10: 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c If it is unabl
8f20: 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 e to promote the
8f30: 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 lock, then the
8f40: 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 in-memory.** cac
8f50: 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 he will be left
8f60: 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 in an inconsiste
8f70: 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 nt state and so
8f80: 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 the error.** cod
8f90: 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 e is promoted fr
8fa0: 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c om the relativel
8fb0: 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 y benign [SQLITE
8fc0: 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 _BUSY] to.** the
8fd0: 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 more severe [SQ
8fe0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
8ff0: 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72 ED]. This error
9000: 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a code promotion.
9010: 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 ** forces an aut
9020: 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 omatic rollback
9030: 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 of the changes.
9040: 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 See the.** <a hr
9050: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73 ef="http://www.s
9060: 71 6c 69 74 65 2e 6f 72 67 2f 63 76 73 74 72 61 qlite.org/cvstra
9070: 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 c/wiki?p=Corrupt
9080: 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 ionFollowingBusy
9090: 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 Error">.** Corru
90a0: 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 ptionFollowingBu
90b0: 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 syError</a> wiki
90c0: 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 page for a disc
90d0: 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a ussion of why.**
90e0: 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 this is importa
90f0: 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 53 71 6c 69 74 nt..**..** Sqlit
9100: 65 20 69 73 20 72 65 2d 65 6e 74 72 61 6e 74 2c e is re-entrant,
9110: 20 73 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e so the busy han
9120: 64 6c 65 72 20 6d 61 79 20 73 74 61 72 74 20 61 dler may start a
9130: 20 6e 65 77 20 71 75 65 72 79 2e 20 0a 2a 2a 20 new query. .**
9140: 28 49 74 20 69 73 20 6e 6f 74 20 63 6c 65 61 72 (It is not clear
9150: 20 77 68 79 20 61 6e 79 6f 6e 65 20 77 6f 75 6c why anyone woul
9160: 64 20 65 76 65 72 79 20 77 61 6e 74 20 74 6f 20 d every want to
9170: 64 6f 20 74 68 69 73 2c 20 62 75 74 20 69 74 0a do this, but it.
9180: 2a 2a 20 69 73 20 61 6c 6c 6f 77 65 64 2c 20 69 ** is allowed, i
9190: 6e 20 74 68 65 6f 72 79 2e 29 20 20 42 75 74 20 n theory.) But
91a0: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
91b0: 20 6d 61 79 20 6e 6f 74 20 63 6c 6f 73 65 20 74 may not close t
91c0: 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 he.** database.
91d0: 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 64 61 74 Closing the dat
91e0: 61 62 61 73 65 20 66 72 6f 6d 20 61 20 62 75 73 abase from a bus
91f0: 79 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20 64 y handler will d
9200: 65 6c 65 74 65 20 0a 2a 2a 20 64 61 74 61 20 73 elete .** data s
9210: 74 72 75 63 74 75 72 65 73 20 6f 75 74 20 66 72 tructures out fr
9220: 6f 6d 20 75 6e 64 65 72 20 74 68 65 20 65 78 65 om under the exe
9230: 63 75 74 69 6e 67 20 71 75 65 72 79 20 61 6e 64 cuting query and
9240: 20 77 69 6c 6c 20 0a 2a 2a 20 70 72 6f 62 61 62 will .** probab
9250: 6c 79 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 ly result in a s
9260: 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c egmentation faul
9270: 74 20 6f 72 20 6f 74 68 65 72 20 72 75 6e 74 69 t or other runti
9280: 6d 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 me error..**.**
9290: 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 There can only b
92a0: 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 e a single busy
92b0: 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 handler defined
92c0: 66 6f 72 20 65 61 63 68 20 64 61 74 61 62 61 73 for each databas
92d0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e e.** connection.
92e0: 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 Setting a new
92f0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 busy handler cle
9300: 61 72 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73 ars any previous
9310: 20 6f 6e 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 one..** Note th
9320: 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 at calling [sqli
9330: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
9340: 28 29 5d 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 ()] will also se
9350: 74 20 6f 72 20 63 6c 65 61 72 0a 2a 2a 20 74 68 t or clear.** th
9360: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a e busy handler..
9370: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 6f 70 65 72 61 **.** When opera
9380: 74 69 6e 67 20 69 6e 20 5b 73 71 6c 69 74 65 33 ting in [sqlite3
9390: 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 _enable_shared_c
93a0: 61 63 68 65 20 7c 20 73 68 61 72 65 64 20 63 61 ache | shared ca
93b0: 63 68 65 20 6d 6f 64 65 5d 2c 0a 2a 2a 20 6f 6e che mode],.** on
93c0: 6c 79 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 ly a single busy
93d0: 20 68 61 6e 64 6c 65 72 20 63 61 6e 20 62 65 20 handler can be
93e0: 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 defined for each
93f0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a database file..
9400: 2a 2a 20 53 6f 20 69 66 20 74 77 6f 20 64 61 74 ** So if two dat
9410: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
9420: 73 20 73 68 61 72 65 20 61 20 73 69 6e 67 6c 65 s share a single
9430: 20 63 61 63 68 65 2c 20 74 68 65 6e 20 63 68 61 cache, then cha
9440: 6e 67 69 6e 67 0a 2a 2a 20 74 68 65 20 62 75 73 nging.** the bus
9450: 79 20 68 61 6e 64 6c 65 72 20 6f 6e 20 6f 6e 65 y handler on one
9460: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 69 6c 6c connection will
9470: 20 61 6c 73 6f 20 63 68 61 6e 67 65 20 74 68 65 also change the
9480: 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 busy.** handler
9490: 20 69 6e 20 74 68 65 20 6f 74 68 65 72 20 63 6f in the other co
94a0: 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 62 nnection. The b
94b0: 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 69 usy handler is i
94c0: 6e 76 6f 6b 65 64 0a 2a 2a 20 69 6e 20 74 68 65 nvoked.** in the
94d0: 20 74 68 72 65 61 64 20 74 68 61 74 20 77 61 73 thread that was
94e0: 20 72 75 6e 6e 69 6e 67 20 77 68 65 6e 20 74 68 running when th
94f0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 77 61 e SQLITE_BUSY wa
9500: 73 20 68 69 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 s hit..*/.int sq
9510: 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
9520: 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 er(sqlite3*, int
9530: 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 (*)(void*,int),
9540: 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
9550: 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 API3REF: Set A B
9560: 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a usy Timeout.**.*
9570: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 * This routine s
9580: 65 74 73 20 61 20 62 75 73 79 20 68 61 6e 64 6c ets a busy handl
9590: 65 72 20 74 68 61 74 20 73 6c 65 65 70 73 20 66 er that sleeps f
95a0: 6f 72 20 61 20 77 68 69 6c 65 20 77 68 65 6e 20 or a while when
95b0: 61 0a 2a 2a 20 74 61 62 6c 65 20 69 73 20 6c 6f a.** table is lo
95c0: 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c cked. The handl
95d0: 65 72 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 er will sleep mu
95e0: 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 ltiple times unt
95f0: 69 6c 20 0a 2a 2a 20 61 74 20 6c 65 61 73 74 20 il .** at least
9600: 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 "ms" millisecond
9610: 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 20 68 61 s of sleeping ha
9620: 76 65 20 62 65 65 6e 20 64 6f 6e 65 2e 20 20 41 ve been done. A
9630: 66 74 65 72 0a 2a 2a 20 22 6d 73 22 20 6d 69 6c fter.** "ms" mil
9640: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 liseconds of sle
9650: 65 70 69 6e 67 2c 20 74 68 65 20 68 61 6e 64 6c eping, the handl
9660: 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 er returns 0 whi
9670: 63 68 0a 2a 2a 20 63 61 75 73 65 73 20 5b 73 71 ch.** causes [sq
9680: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f lite3_step()] to
9690: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
96a0: 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 BUSY] or [SQLITE
96b0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e _IOERR_BLOCKED].
96c0: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 .**.** Calling t
96d0: 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
96e0: 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 an argument les
96f0: 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 s than or equal
9700: 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 to zero.** turns
9710: 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 off all busy ha
9720: 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ndlers..**.** Th
9730: 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ere can only be
9740: 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 a single busy ha
9750: 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 ndler for a part
9760: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a icular database.
9770: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 ** connection.
9780: 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 If another busy
9790: 68 61 6e 64 6c 65 72 20 77 61 73 20 64 65 66 69 handler was defi
97a0: 6e 65 64 20 20 0a 2a 2a 20 28 75 73 69 6e 67 20 ned .** (using
97b0: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 [sqlite3_busy_ha
97c0: 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 ndler()]) prior
97d0: 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 to calling.** th
97e0: 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 is routine, that
97f0: 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 other busy hand
9800: 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a ler is cleared..
9810: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
9820: 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 usy_timeout(sqli
9830: 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a te3*, int ms);..
9840: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
9850: 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 Convenience Rout
9860: 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 ines For Running
9870: 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 Queries.**.** T
9880: 68 69 73 20 6e 65 78 74 20 72 6f 75 74 69 6e 65 his next routine
9890: 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 is a convenienc
98a0: 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 e wrapper around
98b0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
98c0: 5d 2e 0a 2a 2a 20 49 6e 73 74 65 61 64 20 6f 66 ]..** Instead of
98d0: 20 69 6e 76 6f 6b 69 6e 67 20 61 20 75 73 65 72 invoking a user
98e0: 2d 73 75 70 70 6c 69 65 64 20 63 61 6c 6c 62 61 -supplied callba
98f0: 63 6b 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 ck for each row
9900: 6f 66 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 of the.** result
9910: 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 , this routine r
9920: 65 6d 65 6d 62 65 72 73 20 65 61 63 68 20 72 6f emembers each ro
9930: 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 w of the result
9940: 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 in memory.** obt
9950: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
9960: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 74 te3_malloc()], t
9970: 68 65 6e 20 72 65 74 75 72 6e 73 20 61 6c 6c 20 hen returns all
9980: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 61 66 of the result af
9990: 74 65 72 20 74 68 65 0a 2a 2a 20 71 75 65 72 79 ter the.** query
99a0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 2e 20 0a has finished. .
99b0: 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d **.** As an exam
99c0: 70 6c 65 2c 20 73 75 70 70 6f 73 65 20 74 68 65 ple, suppose the
99d0: 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 77 68 query result wh
99e0: 65 72 65 20 74 68 69 73 20 74 61 62 6c 65 3a 0a ere this table:.
99f0: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
9a00: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 e><pre>.**
9a10: 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 Name |
9a20: 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d Age.** --
9a30: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
9a40: 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 -----.**
9a50: 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 Alice | 43
9a60: 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 .** Bob
9a70: 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 | 28.**
9a80: 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 Cindy
9a90: 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e | 21.** </pre>
9aa0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
9ab0: 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 61 .** If the 3rd a
9ac0: 72 67 75 6d 65 6e 74 20 77 65 72 65 20 26 61 7a rgument were &az
9ad0: 52 65 73 75 6c 74 20 74 68 65 6e 20 61 66 74 65 Result then afte
9ae0: 72 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 r the function r
9af0: 65 74 75 72 6e 73 0a 2a 2a 20 61 7a 52 65 73 75 eturns.** azResu
9b00: 6c 74 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 lt will contain
9b10: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 64 61 the following da
9b20: 74 61 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ta:.**.** <block
9b30: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
9b40: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
9b50: 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 91;0] = "Name";.
9b60: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
9b70: 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 lt[1] = "Age
9b80: 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
9b90: 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 esult[2] = "
9ba0: 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 Alice";.**
9bb0: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 azResult[3
9bc0: 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 ] = "43";.**
9bd0: 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
9be0: 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 ;4] = "Bob";.**
9bf0: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
9c00: 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a #91;5] = "28";.*
9c10: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
9c20: 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 t[6] = "Cind
9c30: 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a y";.** az
9c40: 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 Result[7] =
9c50: 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c "21";.** </pre><
9c60: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
9c70: 2a 2a 20 4e 6f 74 69 63 65 20 74 68 61 74 20 74 ** Notice that t
9c80: 68 65 72 65 20 69 73 20 61 6e 20 65 78 74 72 61 here is an extra
9c90: 20 72 6f 77 20 6f 66 20 64 61 74 61 20 63 6f 6e row of data con
9ca0: 74 61 69 6e 69 6e 67 20 74 68 65 20 63 6f 6c 75 taining the colu
9cb0: 6d 6e 0a 2a 2a 20 68 65 61 64 65 72 73 2e 20 20 mn.** headers.
9cc0: 42 75 74 20 74 68 65 20 2a 6e 72 6f 77 20 72 65 But the *nrow re
9cd0: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 20 73 74 turn value is st
9ce0: 69 6c 6c 20 33 2e 20 20 2a 6e 63 6f 6c 75 6d 6e ill 3. *ncolumn
9cf0: 20 69 73 0a 2a 2a 20 73 65 74 20 74 6f 20 32 2e is.** set to 2.
9d00: 20 20 49 6e 20 67 65 6e 65 72 61 6c 2c 20 74 68 In general, th
9d10: 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 e number of valu
9d20: 65 73 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f es inserted into
9d30: 20 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 77 69 6c azResult.** wil
9d40: 6c 20 62 65 20 28 28 2a 6e 72 6f 77 29 20 2b 20 l be ((*nrow) +
9d50: 31 29 2a 28 2a 6e 63 6f 6c 75 6d 6e 29 2e 0a 2a 1)*(*ncolumn)..*
9d60: 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63 *.** After the c
9d70: 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 alling function
9d80: 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 has finished usi
9d90: 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69 ng the result, i
9da0: 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 61 73 t should .** pas
9db0: 73 20 74 68 65 20 72 65 73 75 6c 74 20 64 61 74 s the result dat
9dc0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c a pointer to sql
9dd0: 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 ite3_free_table(
9de0: 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 0a 2a ) in order to .*
9df0: 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 * release the me
9e00: 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 mory that was ma
9e10: 6c 6c 6f 63 2d 65 64 2e 20 20 42 65 63 61 75 73 lloc-ed. Becaus
9e20: 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 e of the way the
9e30: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 .** [sqlite3_ma
9e40: 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 2c lloc()] happens,
9e50: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e the calling fun
9e60: 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 ction must not t
9e70: 72 79 20 74 6f 20 63 61 6c 6c 20 0a 2a 2a 20 5b ry to call .** [
9e80: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
9e90: 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 20 directly. Only
9ea0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 [sqlite3_free_ta
9eb0: 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 ble()] is able t
9ec0: 6f 20 72 65 6c 65 61 73 65 20 0a 2a 2a 20 74 68 o release .** th
9ed0: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c e memory properl
9ee0: 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a y and safely..**
9ef0: 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76 .** The return v
9f00: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 alue of this rou
9f10: 74 69 6e 65 20 69 73 20 74 68 65 20 73 61 6d 65 tine is the same
9f20: 20 61 73 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 as from [sqlite
9f30: 33 5f 65 78 65 63 28 29 5d 2e 0a 2a 2f 0a 69 6e 3_exec()]..*/.in
9f40: 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 t sqlite3_get_ta
9f50: 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c ble(. sqlite3*,
9f60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
9f70: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 An open databas
9f80: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
9f90: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 2f 2a r *sql, /*
9fa0: 20 53 51 4c 20 74 6f 20 62 65 20 65 78 65 63 75 SQL to be execu
9fb0: 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a ted */. char **
9fc0: 2a 72 65 73 75 6c 74 70 2c 20 20 20 20 20 20 20 *resultp,
9fd0: 2f 2a 20 52 65 73 75 6c 74 20 77 72 69 74 74 65 /* Result writte
9fe0: 6e 20 74 6f 20 61 20 63 68 61 72 20 2a 5b 5d 20 n to a char *[]
9ff0: 20 74 68 61 74 20 74 68 69 73 20 70 6f 69 6e 74 that this point
a000: 73 20 74 6f 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e s to */. int *n
a010: 72 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 20 row,
a020: 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 /* Number of re
a030: 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 sult rows writte
a040: 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 n here */. int
a050: 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 *ncolumn,
a060: 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 /* Number of
a070: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 result columns w
a080: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 ritten here */.
a090: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 char **errmsg
a0a0: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 /* Error
a0b0: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 msg written her
a0c0: 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c e */.);.void sql
a0d0: 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 ite3_free_table(
a0e0: 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a char **result);.
a0f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
a100: 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e Formatted Strin
a110: 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 g Printing Funct
a120: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
a130: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f routines are wo
a140: 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 rkalikes of the
a150: 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c "printf()" famil
a160: 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a y of functions.*
a170: 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 * from the stand
a180: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a ard C library..*
a190: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
a1a0: 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 _mprintf() and s
a1b0: 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
a1c0: 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 ) routines write
a1d0: 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 their.** result
a1e0: 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 s into memory ob
a1f0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
a200: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a ite3_malloc()]..
a210: 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 ** The strings r
a220: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 eturned by these
a230: 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 two routines sh
a240: 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 ould be.** relea
a250: 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f sed by [sqlite3_
a260: 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 free()]. Both r
a270: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 outines return a
a280: 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 .** NULL pointer
a290: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c if [sqlite3_mal
a2a0: 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 loc()] is unable
a2b0: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f to allocate eno
a2c0: 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f ugh.** memory to
a2d0: 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 hold the result
a2e0: 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a ing string..**.*
a2f0: 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 * In sqlite3_snp
a300: 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 rintf() routine
a310: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 is similar to "s
a320: 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a nprintf()" from.
a330: 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 ** the standard
a340: 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 C library. The
a350: 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 result is writte
a360: 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 n into the.** bu
a370: 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 ffer supplied as
a380: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
a390: 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 meter whose size
a3a0: 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 is given by.**
a3b0: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
a3c0: 74 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 ter. Note that
a3d0: 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 the order of the
a3e0: 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 .** first two pa
a3f0: 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 rameters is reve
a400: 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e rsed from snprin
a410: 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 tf(). This is a
a420: 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 n.** historical
a430: 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 accident that ca
a440: 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 nnot be fixed wi
a450: 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a thout breaking.*
a460: 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 * backwards comp
a470: 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 atibility. Note
a480: 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 also that sqlit
a490: 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
a4a0: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
a4b0: 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 er to its buffer
a4c0: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
a4d0: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 number of.** cha
a4e0: 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 racters actually
a4f0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
a500: 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 e buffer. We ad
a510: 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 mit that.** the
a520: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
a530: 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 ters written wou
a540: 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 ld be a more use
a550: 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 ful return.** va
a560: 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f lue but we canno
a570: 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 t change the imp
a580: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 lementation of s
a590: 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
a5a0: 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 ).** now without
a5b0: 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 breaking compat
a5c0: 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 ibility..**.** A
a5d0: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 s long as the bu
a5e0: 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 ffer size is gre
a5f0: 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 ater than zero,
a600: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
a610: 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 ().** guarantees
a620: 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 that the buffer
a630: 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d is always zero-
a640: 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 terminated. The
a650: 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 first.** parame
a660: 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 ter "n" is the t
a670: 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 otal size of the
a680: 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 buffer, includi
a690: 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 ng space for.**
a6a0: 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 the zero termina
a6b0: 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e tor. So the lon
a6c0: 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 gest string that
a6d0: 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 can be complete
a6e0: 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 ly.** written wi
a6f0: 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 ll be n-1 charac
a700: 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ters..**.** Thes
a710: 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 e routines all i
a720: 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 mplement some ad
a730: 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 ditional formatt
a740: 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 ing.** options t
a750: 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 hat are useful f
a760: 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 or constructing
a770: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a SQL statements..
a780: 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 ** All of the us
a790: 75 61 6c 20 70 72 69 6e 74 66 20 66 6f 72 6d 61 ual printf forma
a7a0: 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 tting options ap
a7b0: 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f ply. In additio
a7c0: 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 n, there.** is a
a7d0: 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 re "%q", "%Q", a
a7e0: 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e nd "%z" options.
a7f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 .**.** The %q op
a800: 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 tion works like
a810: 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 %s in that it su
a820: 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c bstitutes a null
a830: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 -terminated.** s
a840: 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 tring from the a
a850: 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 rgument list. B
a860: 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c ut %q also doubl
a870: 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 es every '\'' ch
a880: 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 aracter..** %q i
a890: 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 s designed for u
a8a0: 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 se inside a stri
a8b0: 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 ng literal. By
a8c0: 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c doubling each '\
a8d0: 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 ''.** character
a8e0: 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 it escapes that
a8f0: 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c character and al
a900: 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e lows it to be in
a910: 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 serted into.** t
a920: 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a he string..**.**
a930: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 73 6f For example, so
a940: 20 73 6f 6d 65 20 73 74 72 69 6e 67 20 76 61 72 some string var
a950: 69 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74 iable contains t
a960: 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a ext as follows:.
a970: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
a980: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 e><pre>.** char
a990: 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 *zText = "It's
a9a0: 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a a happy day!";.*
a9b0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
a9c0: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 uote>.**.** One
a9d0: 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 can use this tex
a9e0: 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 t in an SQL stat
a9f0: 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 ement as follows
aa00: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
aa10: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 ote><pre>.** ch
aa20: 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 ar *zSQL = sqlit
aa30: 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 e3_mprintf("INSE
aa40: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 RT INTO table VA
aa50: 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 LUES('%q')", zTe
aa60: 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 xt);.** sqlite3
aa70: 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 _exec(db, zSQL,
aa80: 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 0, 0, 0);.** sq
aa90: 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 lite3_free(zSQL)
aaa0: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
aab0: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 ckquote>.**.** B
aac0: 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f ecause the %q fo
aad0: 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 rmat string is u
aae0: 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 sed, the '\'' ch
aaf0: 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 aracter in zText
ab00: 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 .** is escaped a
ab10: 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 nd the SQL gener
ab20: 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f ated is as follo
ab30: 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
ab40: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
ab50: 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
ab60: 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 e1 VALUES('It''s
ab70: 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a a happy day!').
ab80: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
ab90: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 quote>.**.** Thi
aba0: 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 s is correct. H
abb0: 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e ad we used %s in
abc0: 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 stead of %q, the
abd0: 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a generated SQL.*
abe0: 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f * would have loo
abf0: 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a ked like this:.*
ac00: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
ac10: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 ><pre>.** INSER
ac20: 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 T INTO table1 VA
ac30: 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 LUES('It's a hap
ac40: 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f py day!');.** </
ac50: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
ac60: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 >.**.** This sec
ac70: 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 ond example is a
ac80: 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 n SQL syntax err
ac90: 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 or. As a genera
aca0: 6c 20 72 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 68 l rule you.** sh
acb0: 6f 75 6c 64 20 61 6c 77 61 79 73 20 75 73 65 20 ould always use
acc0: 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 %q instead of %s
acd0: 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 when inserting
ace0: 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 text into a stri
acf0: 6e 67 20 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a ng .** literal..
ad00: 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 **.** The %Q opt
ad10: 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 ion works like %
ad20: 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f q except it also
ad30: 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f adds single quo
ad40: 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 tes around.** th
ad50: 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 e outside of the
ad60: 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 total string.
ad70: 4f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 Or if the parame
ad80: 74 65 72 20 69 6e 20 74 68 65 20 61 72 67 75 6d ter in the argum
ad90: 65 6e 74 0a 2a 2a 20 6c 69 73 74 20 69 73 20 61 ent.** list is a
ada0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 NULL pointer, %
adb0: 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 Q substitutes th
adc0: 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 e text "NULL" (w
add0: 69 74 68 6f 75 74 20 73 69 6e 67 6c 65 0a 2a 2a ithout single.**
ade0: 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 quotes) in plac
adf0: 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69 e of the %Q opti
ae00: 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 on. So, for exa
ae10: 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 mple, one could
ae20: 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 say:.**.** <bloc
ae30: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
ae40: 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 char *zSQL = sq
ae50: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 lite3_mprintf("I
ae60: 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 NSERT INTO table
ae70: 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 VALUES(%Q)", zT
ae80: 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 ext);.** sqlite
ae90: 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 3_exec(db, zSQL,
aea0: 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 0, 0, 0);.** s
aeb0: 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c qlite3_free(zSQL
aec0: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
aed0: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
aee0: 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 The code above w
aef0: 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 ill render a cor
af00: 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 rect SQL stateme
af10: 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a nt in the zSQL.*
af20: 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 * variable even
af30: 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 if the zText var
af40: 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 iable is a NULL
af50: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 pointer..**.** T
af60: 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 he "%z" formatti
af70: 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 ng option works
af80: 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 exactly like "%s
af90: 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 " with the.** ad
afa0: 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 dition that afte
afb0: 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 r the string has
afc0: 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 been read and c
afd0: 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 opied into.** th
afe0: 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 e result, [sqlit
aff0: 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 e3_free()] is ca
b000: 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 lled on the inpu
b010: 74 20 73 74 72 69 6e 67 2e 0a 2a 2f 0a 63 68 61 t string..*/.cha
b020: 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e r *sqlite3_mprin
b030: 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e tf(const char*,.
b040: 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 ..);.char *sqlit
b050: 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 e3_vmprintf(cons
b060: 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 t char*, va_list
b070: 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 );.char *sqlite3
b080: 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 _snprintf(int,ch
b090: 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
b0a0: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ...);../*.** CA
b0b0: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
b0c0: 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 llocation Subsys
b0d0: 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 tem.**.** The SQ
b0e0: 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 Lite core uses t
b0f0: 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 hese three routi
b100: 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 nes for all of i
b110: 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e ts own.** intern
b120: 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 al memory alloca
b130: 74 69 6f 6e 20 6e 65 65 64 73 2e 20 54 68 65 20 tion needs. The
b140: 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e default implemen
b150: 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 tation.** of the
b160: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
b170: 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65 on subsystem use
b180: 73 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 s the malloc(),
b190: 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 61 6e 64 realloc().** and
b1a0: 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64 free() provided
b1b0: 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64 by the standard
b1c0: 20 43 20 6c 69 62 72 61 72 79 2e 20 20 48 6f 77 C library. How
b1d0: 65 76 65 72 2c 20 69 66 20 0a 2a 2a 20 53 51 4c ever, if .** SQL
b1e0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
b1f0: 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69 with the followi
b200: 6e 67 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f ng C preprocesso
b210: 72 20 6d 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62 r macro.**.** <b
b220: 6c 6f 63 6b 71 75 6f 74 65 3e 20 53 51 4c 49 54 lockquote> SQLIT
b230: 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c E_OMIT_MEMORY_AL
b240: 4c 4f 43 41 54 49 4f 4e 20 3c 2f 62 6c 6f 63 6b LOCATION </block
b250: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 74 68 65 quote>.**.** the
b260: 6e 20 6e 6f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 n no implementat
b270: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 ion is provided
b280: 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e for these routin
b290: 65 73 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 2e es by.** SQLite.
b2a0: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f The applicatio
b2b0: 6e 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 n that links aga
b2c0: 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a inst SQLite is.*
b2d0: 2a 20 65 78 70 65 63 74 65 64 20 74 6f 20 70 72 * expected to pr
b2e0: 6f 76 69 64 65 20 69 74 73 20 6f 77 6e 20 69 6d ovide its own im
b2f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 49 plementation. I
b300: 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
b310: 6e 0a 2a 2a 20 64 6f 65 73 20 70 72 6f 76 69 64 n.** does provid
b320: 65 20 69 74 73 20 6f 77 6e 20 69 6d 70 6c 65 6d e its own implem
b330: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 entation for the
b340: 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 74 68 65 se routines, the
b350: 6e 0a 2a 2a 20 69 74 20 6d 75 73 74 20 61 6c 73 n.** it must als
b360: 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69 6d 70 o provide an imp
b370: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a lementation for.
b380: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f ** [sqlite3_memo
b390: 72 79 5f 61 6c 61 72 6d 28 29 5d 2e 0a 2a 2a 0a ry_alarm()]..**.
b3a0: 2a 2a 20 3c 62 3e 45 78 63 65 70 74 69 6f 6e 3a ** <b>Exception:
b3b0: 3c 2f 62 3e 20 54 68 65 20 77 69 6e 64 6f 77 73 </b> The windows
b3c0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 OS interface la
b3d0: 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 yer calls.** the
b3e0: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 system malloc()
b3f0: 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 and free() dire
b400: 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 ctly when conver
b410: 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 ting.** filename
b420: 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 s between the UT
b430: 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 F-8 encoding use
b440: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 d by SQLite.** a
b450: 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 nd whatever file
b460: 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 name encoding is
b470: 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 used by the par
b480: 74 69 63 75 6c 61 72 20 77 69 6e 64 6f 77 73 0a ticular windows.
b490: 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e ** installation.
b4a0: 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 Memory allocat
b4b0: 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 ion errors are d
b4c0: 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 etected, but.**
b4d0: 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 they are reporte
b4e0: 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 d back as [SQLIT
b4f0: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a E_CANTOPEN] or.*
b500: 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d * [SQLITE_IOERR]
b510: 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 rather than [SQ
b520: 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a LITE_NOMEM]..*/.
b530: 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 void *sqlite3_ma
b540: 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 lloc(int);.void
b550: 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 *sqlite3_realloc
b560: 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f (void*, int);.vo
b570: 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 id sqlite3_free(
b580: 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
b590: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 API3REF: Memory
b5a0: 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 Allocator Statis
b5b0: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 61 64 tics.**.** In ad
b5c0: 64 69 74 69 6f 6e 20 74 6f 20 74 68 65 20 62 61 dition to the ba
b5d0: 73 69 63 20 74 68 72 65 65 20 61 6c 6c 6f 63 61 sic three alloca
b5e0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 0a 2a tion routines .*
b5f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f * [sqlite3_mallo
b600: 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 c()], [sqlite3_f
b610: 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c ree()], and [sql
b620: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c ite3_realloc()],
b630: 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 .** the memory a
b640: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
b650: 74 65 6d 20 69 6e 63 6c 75 64 65 64 20 77 69 74 tem included wit
b660: 68 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 h the SQLite.**
b670: 73 6f 75 72 63 65 73 20 70 72 6f 76 69 64 65 73 sources provides
b680: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 the interfaces
b690: 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 0a shown below..**.
b6a0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 6f 66 20 ** The first of
b6b0: 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e these two routin
b6c0: 65 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 es returns the a
b6d0: 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 mount of memory
b6e0: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 .** currently ou
b6f0: 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f tstanding (mallo
b700: 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 ced but not free
b710: 64 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 0a d). The second.
b720: 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c ** returns the l
b730: 61 72 67 65 73 74 20 69 6e 73 74 61 6e 74 61 6e argest instantan
b740: 65 6f 75 73 20 61 6d 6f 75 6e 74 20 6f 66 20 6f eous amount of o
b750: 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 6d 65 utstanding.** me
b760: 6d 6f 72 79 2e 20 20 54 68 65 20 68 69 67 68 77 mory. The highw
b770: 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 ater mark is res
b780: 65 74 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 et if the argume
b790: 6e 74 20 69 73 0a 2a 2a 20 74 72 75 65 2e 20 20 nt is.** true.
b7a0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
b7b0: 64 6f 65 73 20 6e 6f 74 20 75 73 65 20 65 69 74 does not use eit
b7c0: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 her of these rou
b7d0: 74 69 6e 65 73 0a 2a 2a 20 61 6e 64 20 73 6f 20 tines.** and so
b7e0: 74 68 65 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 they do not have
b7f0: 20 74 6f 20 62 65 20 69 6d 70 6c 65 6d 65 6e 74 to be implement
b800: 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ed by the applic
b810: 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 53 51 4c 49 ation.** if SQLI
b820: 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 TE_OMIT_MEMORY_A
b830: 4c 4c 4f 43 41 54 49 4f 4e 20 69 73 20 64 65 66 LLOCATION is def
b840: 69 6e 65 64 2e 20 20 54 68 65 73 65 20 72 6f 75 ined. These rou
b850: 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 72 6f tines.** are pro
b860: 76 69 64 65 64 20 62 79 20 74 68 65 20 64 65 66 vided by the def
b870: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 73 75 62 73 ault memory subs
b880: 79 73 74 65 6d 20 66 6f 72 20 64 69 61 67 6e 6f ystem for diagno
b890: 73 74 69 63 0a 2a 2a 20 70 75 72 70 6f 73 65 73 stic.** purposes
b8a0: 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 ..*/.sqlite3_int
b8b0: 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 64 sqlite3_memor
b8c0: 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 y_used(void);.sq
b8d0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
b8e0: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
b8f0: 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c ater(int resetFl
b900: 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ag);../*.** CAPI
b910: 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
b920: 6f 63 61 74 69 6f 6e 20 41 6c 61 72 6d 73 0a 2a ocation Alarms.*
b930: 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 *.** The [sqlite
b940: 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 5d 20 3_memory_alarm]
b950: 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 routine is used
b960: 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 61 to register.** a
b970: 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 6d 65 6d callback on mem
b980: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
b990: 76 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 vents..**.** Thi
b9a0: 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 s routine regist
b9b0: 65 72 73 20 6f 72 20 63 6c 65 61 72 73 20 61 20 ers or clears a
b9c0: 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 66 callbacks that f
b9d0: 69 72 65 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65 ires when.** the
b9e0: 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 amount of memor
b9f0: 79 20 61 6c 6c 6f 63 61 74 65 64 20 65 78 63 65 y allocated exce
ba00: 65 64 73 20 69 54 68 72 65 73 68 6f 6c 64 2e 20 eds iThreshold.
ba10: 20 4f 6e 6c 79 0a 2a 2a 20 61 20 73 69 6e 67 6c Only.** a singl
ba20: 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 62 e callback can b
ba30: 65 20 72 65 67 69 73 74 65 72 65 64 20 61 74 20 e registered at
ba40: 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 a time. Each ca
ba50: 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 ll.** to [sqlite
ba60: 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 29 3_memory_alarm()
ba70: 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 ] overwrites the
ba80: 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 62 61 previous callba
ba90: 63 6b 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 ck..** The callb
baa0: 61 63 6b 20 69 73 20 64 69 73 61 62 6c 65 64 20 ack is disabled
bab0: 62 79 20 73 65 74 74 69 6e 67 20 78 43 61 6c 6c by setting xCall
bac0: 62 61 63 6b 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a back to a NULL.*
bad0: 2a 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 0a 2a * pointer..** .*
bae0: 2a 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 73 * The parameters
baf0: 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
bb00: 20 61 72 65 20 74 68 65 20 70 41 72 67 20 76 61 are the pArg va
bb10: 6c 75 65 2c 20 74 68 65 20 0a 2a 2a 20 61 6d 6f lue, the .** amo
bb20: 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 unt of memory cu
bb30: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2c 20 rrently in use,
bb40: 61 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 and the size of
bb50: 74 68 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f the.** allocatio
bb60: 6e 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 n that provoked
bb70: 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 the callback. T
bb80: 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c he callback will
bb90: 0a 2a 2a 20 70 72 65 73 75 6d 61 62 6c 79 20 69 .** presumably i
bba0: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 nvoke [sqlite3_f
bbb0: 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65 20 75 ree()] to free u
bbc0: 70 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 2e 0a p memory space..
bbd0: 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 ** The callback
bbe0: 6d 61 79 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 may invoke [sqli
bbf0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 te3_malloc()] or
bc00: 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
bc10: 63 28 29 5d 0a 2a 2a 20 62 75 74 20 69 66 20 69 c()].** but if i
bc20: 74 20 64 6f 65 73 2c 20 6e 6f 20 61 64 64 69 74 t does, no addit
bc30: 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 ional callbacks
bc40: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 will be invoked
bc50: 62 79 0a 2a 2a 20 74 68 65 20 72 65 63 75 72 73 by.** the recurs
bc60: 69 76 65 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a ive calls..**.**
bc70: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f The [sqlite3_so
bc80: 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d ft_heap_limit()]
bc90: 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 interface works
bca0: 20 62 79 20 72 65 67 69 73 74 65 72 69 6e 67 0a by registering.
bcb0: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 61 72 ** a memory alar
bcc0: 6d 20 61 74 20 74 68 65 20 73 6f 66 74 20 68 65 m at the soft he
bcd0: 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 69 6e 76 ap limit and inv
bce0: 6f 6b 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 oking .** [sqlit
bcf0: 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 e3_release_memor
bd00: 79 28 29 5d 20 69 6e 20 74 68 65 20 61 6c 61 72 y()] in the alar
bd10: 6d 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 70 70 m callback. App
bd20: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 6f 67 lication.** prog
bd30: 72 61 6d 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 rams should not
bd40: 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 attempt to use t
bd50: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f he [sqlite3_memo
bd60: 72 79 5f 61 6c 61 72 6d 28 29 5d 0a 2a 2a 20 69 ry_alarm()].** i
bd70: 6e 74 65 72 66 61 63 65 20 62 65 63 61 75 73 65 nterface because
bd80: 20 64 6f 69 6e 67 20 73 6f 20 77 69 6c 6c 20 69 doing so will i
bd90: 6e 74 65 72 66 65 72 65 20 77 69 74 68 20 74 68 nterfere with th
bda0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f e.** [sqlite3_so
bdb0: 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d ft_heap_limit()]
bdc0: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 69 73 20 69 module. This i
bdd0: 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 6f nterface is expo
bde0: 73 65 64 0a 2a 2a 20 6f 6e 6c 79 20 73 6f 20 74 sed.** only so t
bdf0: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 hat applications
be00: 20 63 61 6e 20 70 72 6f 76 69 64 65 20 74 68 65 can provide the
be10: 69 72 20 6f 77 6e 0a 2a 2a 20 61 6c 74 65 72 6e ir own.** altern
be20: 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 ative implementa
be30: 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 53 51 tion when the SQ
be40: 4c 69 74 65 20 63 6f 72 65 20 69 73 0a 2a 2a 20 Lite core is.**
be50: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 53 51 compiled with SQ
be60: 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 LITE_OMIT_MEMORY
be70: 5f 41 4c 4c 4f 43 41 54 49 4f 4e 2e 0a 2a 2f 0a _ALLOCATION..*/.
be80: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f int sqlite3_memo
be90: 72 79 5f 61 6c 61 72 6d 28 0a 20 20 76 6f 69 64 ry_alarm(. void
bea0: 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 76 6f 69 (*xCallback)(voi
beb0: 64 20 2a 70 41 72 67 2c 20 73 71 6c 69 74 65 33 d *pArg, sqlite3
bec0: 5f 69 6e 74 36 34 20 75 73 65 64 2c 20 69 6e 74 _int64 used, int
bed0: 20 4e 29 2c 0a 20 20 76 6f 69 64 20 2a 70 41 72 N),. void *pAr
bee0: 67 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 g,. sqlite3_int
bef0: 36 34 20 69 54 68 72 65 73 68 6f 6c 64 0a 29 3b 64 iThreshold.);
bf00: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
bf10: 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 F: Compile-Time
bf20: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 Authorization Ca
bf30: 6c 6c 62 61 63 6b 73 0a 2a 2a 2a 0a 2a 2a 20 54 llbacks.***.** T
bf40: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 his routine regi
bf50: 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a sters a authoriz
bf60: 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 er callback with
bf70: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
bf80: 61 72 79 2e 20 20 0a 2a 2a 20 54 68 65 20 61 75 ary. .** The au
bf90: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
bfa0: 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 k is invoked as
bfb0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 SQL statements a
bfc0: 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 re being compile
bfd0: 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 d.** by [sqlite3
bfe0: 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 _prepare()] or i
bff0: 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c ts variants [sql
c000: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
c010: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
c020: 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 prepare16()] and
c030: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
c040: 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 e16_v2()]. At v
c050: 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 arious.** points
c060: 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 during the comp
c070: 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c ilation process,
c080: 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 as logic is bei
c090: 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f ng created.** to
c0a0: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 perform various
c0b0: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 actions, the au
c0c0: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
c0d0: 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a k is invoked to.
c0e0: 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 ** see if those
c0f0: 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f actions are allo
c100: 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 wed. The author
c110: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 izer callback sh
c120: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 53 ould.** return S
c130: 51 4c 49 54 45 5f 4f 4b 20 74 6f 20 61 6c 6c 6f QLITE_OK to allo
c140: 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 w the action, [S
c150: 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f QLITE_IGNORE] to
c160: 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a disallow the.**
c170: 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e specific action
c180: 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 but allow the S
c190: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 QL statement to
c1a0: 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a continue to be.*
c1b0: 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b * compiled, or [
c1c0: 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 SQLITE_DENY] to
c1d0: 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 cause the entire
c1e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
c1f0: 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 o be.** rejected
c200: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 with an error.
c210: 20 0a 2a 2a 0a 2a 2a 20 44 65 70 65 6e 64 69 6e .**.** Dependin
c220: 67 20 6f 6e 20 74 68 65 20 61 63 74 69 6f 6e 2c g on the action,
c230: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e the [SQLITE_IGN
c240: 4f 52 45 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 ORE] and [SQLITE
c250: 5f 44 45 4e 59 5d 20 72 65 74 75 72 6e 0a 2a 2a _DENY] return.**
c260: 20 63 6f 64 65 73 20 6d 69 67 68 74 20 6d 65 61 codes might mea
c270: 6e 20 73 6f 6d 65 74 68 69 6e 67 20 64 69 66 66 n something diff
c280: 65 72 65 6e 74 20 6f 72 20 74 68 65 79 20 6d 69 erent or they mi
c290: 67 68 74 20 6d 65 61 6e 20 74 68 65 20 73 61 6d ght mean the sam
c2a0: 65 0a 2a 2a 20 74 68 69 6e 67 2e 20 20 49 66 20 e.** thing. If
c2b0: 74 68 65 20 61 63 74 69 6f 6e 20 69 73 2c 20 66 the action is, f
c2c0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 70 or example, to p
c2d0: 65 72 66 6f 72 6d 20 61 20 64 65 6c 65 74 65 20 erform a delete
c2e0: 6f 70 65 72 74 69 6f 6e 2c 0a 2a 2a 20 74 68 65 opertion,.** the
c2f0: 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 n [SQLITE_IGNORE
c300: 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 44 45 ] and [SQLITE_DE
c310: 4e 59 5d 20 62 6f 74 68 20 63 61 75 73 65 20 74 NY] both cause t
c320: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d he statement com
c330: 70 69 6c 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 pilation.** to f
c340: 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f ail with an erro
c350: 72 2e 20 20 42 75 74 20 69 66 20 74 68 65 20 61 r. But if the a
c360: 63 74 69 6f 6e 20 69 73 20 74 6f 20 72 65 61 64 ction is to read
c370: 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 a specific colu
c380: 6d 6e 0a 2a 2a 20 66 72 6f 6d 20 61 20 73 70 65 mn.** from a spe
c390: 63 69 66 69 63 20 74 61 62 6c 65 2c 20 74 68 65 cific table, the
c3a0: 6e 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 n [SQLITE_DENY]
c3b0: 77 69 6c 6c 20 63 61 75 73 65 20 74 68 65 20 65 will cause the e
c3c0: 6e 74 69 72 65 0a 2a 2a 20 73 74 61 74 65 6d 65 ntire.** stateme
c3d0: 6e 74 20 74 6f 20 66 61 69 6c 20 62 75 74 20 5b nt to fail but [
c3e0: 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 77 SQLITE_IGNORE] w
c3f0: 69 6c 6c 20 63 61 75 73 65 20 61 20 4e 55 4c 4c ill cause a NULL
c400: 20 76 61 6c 75 65 20 74 6f 20 62 65 0a 2a 2a 20 value to be.**
c410: 72 65 61 64 20 69 6e 73 74 65 61 64 20 6f 66 20 read instead of
c420: 74 68 65 20 61 63 74 75 61 6c 20 63 6f 6c 75 6d the actual colum
c430: 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 n value..**.** T
c440: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
c450: 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 er to the author
c460: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
c470: 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 a copy of.** th
c480: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
c490: 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
c4a0: 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
c4b0: 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 ) interface..**
c4c0: 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
c4d0: 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c eter to the call
c4e0: 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 back is an integ
c4f0: 65 72 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 er .** [SQLITE_C
c500: 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 OPY | action cod
c510: 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 e] that specifie
c520: 73 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 s the particular
c530: 20 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65 action.** to be
c540: 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 authorized. Th
c550: 65 20 61 76 61 69 6c 61 62 6c 65 20 61 63 74 69 e available acti
c560: 6f 6e 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 on codes are.**
c570: 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 64 [SQLITE_COPY | d
c580: 6f 63 75 6d 65 6e 74 65 64 20 73 65 70 61 72 61 ocumented separa
c590: 74 65 6c 79 5d 2e 20 20 54 68 65 20 74 68 69 72 tely]. The thir
c5a0: 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 0a d through sixth.
c5b0: 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f ** parameters to
c5c0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 the callback ar
c5d0: 65 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 e strings that c
c5e0: 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 ontain additiona
c5f0: 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f l.** details abo
c600: 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f ut the action to
c610: 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a be authorized..
c620: 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 **.** An authori
c630: 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e zer is used when
c640: 20 70 72 65 70 61 72 69 6e 67 20 53 51 4c 20 73 preparing SQL s
c650: 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 tatements from a
c660: 6e 20 75 6e 74 72 75 73 74 65 64 0a 2a 2a 20 73 n untrusted.** s
c670: 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 ource, to ensure
c680: 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 that the SQL st
c690: 61 74 65 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20 atements do not
c6a0: 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 try to access da
c6b0: 74 61 0a 2a 2a 20 74 68 61 74 20 74 68 65 79 20 ta.** that they
c6c0: 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 are not allowed
c6d0: 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 to see, or that
c6e0: 74 68 65 79 20 64 6f 20 6e 6f 74 20 74 72 79 20 they do not try
c6f0: 74 6f 0a 2a 2a 20 65 78 65 63 75 74 65 20 6d 61 to.** execute ma
c700: 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e licious statemen
c710: 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 ts that damage t
c720: 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f he database. Fo
c730: 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e r.** example, an
c740: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 application may
c750: 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f allow a user to
c760: 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 enter arbitrary
c770: 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 .** SQL queries
c780: 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 for evaluation b
c790: 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 y a database. B
c7a0: 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ut the applicati
c7b0: 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 on does.** not w
c7c0: 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 ant the user to
c7d0: 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 be able to make
c7e0: 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 arbitrary change
c7f0: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 s to the.** data
c800: 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 base. An author
c810: 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 izer could then
c820: 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 be put in place
c830: 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 while the.** use
c840: 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 r-entered SQL is
c850: 20 62 65 69 6e 67 20 70 72 65 70 61 72 65 64 20 being prepared
c860: 74 68 61 74 20 64 69 73 61 6c 6c 6f 77 73 20 65 that disallows e
c870: 76 65 72 79 74 68 69 6e 67 0a 2a 2a 20 65 78 63 verything.** exc
c880: 65 70 74 20 53 45 4c 45 43 54 20 73 74 61 74 65 ept SELECT state
c890: 6d 65 6e 74 73 2e 20 20 0a 2a 2a 0a 2a 2a 20 4f ments. .**.** O
c8a0: 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 nly a single aut
c8b0: 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 horizer can be i
c8c0: 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 n place on a dat
c8d0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
c8e0: 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 .** at a time.
c8f0: 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c Each call to sql
c900: 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
c910: 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 zer overrides th
c920: 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 e.** previous ca
c930: 6c 6c 2e 20 20 41 20 4e 55 4c 4c 20 61 75 74 68 ll. A NULL auth
c940: 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 orizer means tha
c950: 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 t no authorizati
c960: 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 on.** callback i
c970: 73 20 69 6e 76 6f 6b 65 64 2e 20 20 54 68 65 20 s invoked. The
c980: 64 65 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a default authoriz
c990: 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a er is NULL..**.*
c9a0: 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 * Note that the
c9b0: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
c9c0: 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f ack is invoked o
c9d0: 6e 6c 79 20 64 75 72 69 6e 67 20 0a 2a 2a 20 5b nly during .** [
c9e0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
c9f0: 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e )] or its varian
ca00: 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 ts. Authorizati
ca10: 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 on is not.** per
ca20: 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 formed during st
ca30: 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 atement evaluati
ca40: 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 on in [sqlite3_s
ca50: 74 65 70 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 tep()]..*/.int s
ca60: 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
ca70: 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 rizer(. sqlite3
ca80: 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 *,. int (*xAuth
ca90: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
caa0: 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
cab0: 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
cac0: 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 const char*),.
cad0: 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a void *pUserData.
cae0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
caf0: 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 EF: Authorizer R
cb00: 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a eturn Codes.**.*
cb10: 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 * The [sqlite3_s
cb20: 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 et_authorizer |
cb30: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
cb40: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 ack function] mu
cb50: 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 st.** return eit
cb60: 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 her [SQLITE_OK]
cb70: 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 or one of these
cb80: 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e two constants in
cb90: 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 order.** to sig
cba0: 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 nal SQLite wheth
cbb0: 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 er or not the ac
cbc0: 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 tion is permitte
cbd0: 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b d. See the.** [
cbe0: 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
cbf0: 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 orizer | authori
cc00: 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f zer documentatio
cc10: 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 n] for additiona
cc20: 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e l.** information
cc30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
cc40: 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f ITE_DENY 1 /
cc50: 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 * Abort the SQL
cc60: 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 statement with a
cc70: 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 n error */.#defi
cc80: 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 ne SQLITE_IGNORE
cc90: 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 2 /* Don't al
cca0: 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 low access, but
ccb0: 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 don't generate a
ccc0: 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a n error */../*.*
ccd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 * CAPI3REF: Auth
cce0: 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f orizer Action Co
ccf0: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 des.**.** The [s
cd00: 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
cd10: 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 rizer()] interfa
cd20: 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 ce registers a c
cd30: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
cd40: 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f .** that is invo
cd50: 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 ked to authorize
cd60: 72 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 r certain SQL st
cd70: 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e atement actions.
cd80: 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 The.** second
cd90: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
cda0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
cdb0: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 integer code tha
cdc0: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 t specifies.** w
cdd0: 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 hat action is be
cde0: 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 ing authorized.
cdf0: 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 These are the i
ce00: 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f nteger action co
ce10: 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 des that.** the
ce20: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
ce30: 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 ack may be passe
ce40: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 d..**.** These a
ce50: 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 ction code value
ce60: 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b s signify what k
ce70: 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e ind of operation
ce80: 20 69 73 20 74 6f 20 62 65 20 0a 2a 2a 20 61 75 is to be .** au
ce90: 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 thorized. The 3
cea0: 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d rd and 4th param
ceb0: 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 eters to the aut
cec0: 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 horization callb
ced0: 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ack.** function
cee0: 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 will be paramete
cef0: 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e rs or NULL depen
cf00: 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 ding on which of
cf10: 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 these.** codes
cf20: 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 is used as the s
cf30: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e econd parameter.
cf40: 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 The 5th parame
cf50: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 ter to the.** au
cf60: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
cf70: 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 k is the name of
cf80: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 the database ("
cf90: 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 0a main", "temp", .
cfa0: 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c ** etc.) if appl
cfb0: 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 icable. The 6th
cfc0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
cfd0: 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
cfe0: 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 lback.** is the
cff0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 name of the inne
d000: 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f r-most trigger o
d010: 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 r view that is r
d020: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a esponsible for.*
d030: 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 * the access att
d040: 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 empt or NULL if
d050: 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 this access atte
d060: 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 mpt is directly
d070: 66 72 6f 6d 20 0a 2a 2a 20 74 6f 70 2d 6c 65 76 from .** top-lev
d080: 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a el SQL code..*/.
d090: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /***************
d0a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
d0b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 ************ 3rd
d0c0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 ************ 4t
d0d0: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 h ***********/.#
d0e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
d0f0: 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 EATE_INDEX
d100: 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 1 /* Index
d110: 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
d120: 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
d130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
d140: 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 ATE_TABLE
d150: 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 2 /* Table
d160: 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
d170: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
d180: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
d190: 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 TE_TEMP_INDEX
d1a0: 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 3 /* Index N
d1b0: 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
d1c0: 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
d1d0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
d1e0: 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 E_TEMP_TABLE
d1f0: 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 4 /* Table Na
d200: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
d210: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
d220: 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
d230: 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 _TEMP_TRIGGER
d240: 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 5 /* Trigger N
d250: 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
d260: 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
d270: 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
d280: 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 TEMP_VIEW 6
d290: 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
d2a0: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
d2b0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
d2c0: 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
d2d0: 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 RIGGER 7
d2e0: 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
d2f0: 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
d300: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
d310: 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 SQLITE_CREATE_VI
d320: 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 EW 8
d330: 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
d340: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
d350: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
d360: 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 QLITE_DELETE
d370: 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 9
d380: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
d390: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
d3a0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
d3b0: 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 LITE_DROP_INDEX
d3c0: 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 10 /
d3d0: 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
d3e0: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
d3f0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
d400: 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 ITE_DROP_TABLE
d410: 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 11 /*
d420: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
d430: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
d440: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
d450: 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 TE_DROP_TEMP_IND
d460: 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 EX 12 /*
d470: 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
d480: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
d490: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
d4a0: 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c E_DROP_TEMP_TABL
d4b0: 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 E 13 /* T
d4c0: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
d4d0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
d4e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
d4f0: 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 _DROP_TEMP_TRIGG
d500: 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 ER 14 /* Tr
d510: 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger Name Ta
d520: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
d530: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d540: 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 DROP_TEMP_VIEW
d550: 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 15 /* Vie
d560: 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w Name NUL
d570: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
d580: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
d590: 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 ROP_TRIGGER
d5a0: 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 16 /* Trig
d5b0: 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
d5c0: 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
d5d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
d5e0: 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 OP_VIEW
d5f0: 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 17 /* View
d600: 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
d610: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
d620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 efine SQLITE_INS
d630: 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 ERT
d640: 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 18 /* Table
d650: 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
d660: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
d670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 fine SQLITE_PRAG
d680: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 MA
d690: 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 19 /* Pragma
d6a0: 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 Name 1st arg
d6b0: 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 or NULL */.#def
d6c0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 ine SQLITE_READ
d6d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
d6e0: 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 20 /* Table Na
d6f0: 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e me Column N
d700: 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
d710: 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 ne SQLITE_SELECT
d720: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
d730: 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 1 /* NULL
d740: 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
d750: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
d760: 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 e SQLITE_TRANSAC
d770: 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 TION 22
d780: 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 /* NULL
d790: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
d7a0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
d7b0: 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 SQLITE_UPDATE
d7c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 23
d7d0: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
d7e0: 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 Column Name
d7f0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
d800: 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 SQLITE_ATTACH
d810: 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 24
d820: 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 /* Filename
d830: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
d840: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
d850: 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 QLITE_DETACH
d860: 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 25
d870: 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 /* Database Name
d880: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
d890: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
d8a0: 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 LITE_ALTER_TABLE
d8b0: 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 26 /
d8c0: 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 * Database Name
d8d0: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
d8e0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
d8f0: 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 ITE_REINDEX
d900: 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 27 /*
d910: 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
d920: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
d930: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
d940: 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 TE_ANALYZE
d950: 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 28 /*
d960: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
d970: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
d980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
d990: 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 E_CREATE_VTABLE
d9a0: 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 29 /* T
d9b0: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d able Name M
d9c0: 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a odule Name *
d9d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
d9e0: 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 _DROP_VTABLE
d9f0: 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 30 /* Ta
da00: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f ble Name Mo
da10: 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f dule Name */
da20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
da30: 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 FUNCTION
da40: 20 20 20 20 20 33 31 20 20 20 2f 2a 20 46 75 6e 31 /* Fun
da50: 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c ction Name NUL
da60: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
da70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
da80: 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 OPY
da90: 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 0 /* No l
daa0: 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f onger used */../
dab0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
dac0: 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 racing And Profi
dad0: 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a ling Functions.*
dae0: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
daf0: 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c nes register cal
db00: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 lback functions
db10: 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 that can be used
db20: 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 for.** tracing
db30: 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 and profiling th
db40: 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 e execution of S
db50: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a QL statements..*
db60: 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 * The callback f
db70: 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
db80: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 ed by sqlite3_tr
db90: 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ace() is invoked
dba0: 0a 2a 2a 20 61 74 20 74 68 65 20 66 69 72 73 74 .** at the first
dbb0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
dbc0: 5d 20 66 6f 72 20 74 68 65 20 65 76 61 6c 75 61 ] for the evalua
dbd0: 74 69 6f 6e 20 6f 66 20 61 6e 20 53 51 4c 20 73 tion of an SQL s
dbe0: 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 tatement..** The
dbf0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
dc00: 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 on registered by
dc10: 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 sqlite3_profile
dc20: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a () is invoked.**
dc30: 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 as each SQL sta
dc40: 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 20 tement finishes
dc50: 61 6e 64 20 69 6e 63 6c 75 64 65 73 0a 2a 2a 20 and includes.**
dc60: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6f 6e 20 68 information on h
dc70: 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 ow long that sta
dc80: 74 65 6d 65 6e 74 20 72 61 6e 2e 0a 2a 2a 0a 2a tement ran..**.*
dc90: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 * The sqlite3_pr
dca0: 6f 66 69 6c 65 28 29 20 41 50 49 20 69 73 20 63 ofile() API is c
dcb0: 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 urrently conside
dcc0: 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c red experimental
dcd0: 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 and.** is subje
dce0: 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f ct to change..*/
dcf0: 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 .void *sqlite3_t
dd00: 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 race(sqlite3*, v
dd10: 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 oid(*xTrace)(voi
dd20: 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c d*,const char*),
dd30: 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 void*);.void *s
dd40: 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 qlite3_profile(s
dd50: 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 qlite3*,. void
dd60: 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 (*xProfile)(void
dd70: 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 *,const char*,sq
dd80: 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 lite3_uint64), v
dd90: 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
dda0: 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 PI3REF: Query Pr
ddb0: 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 ogress Callbacks
ddc0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
ddd0: 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 ine configures a
dde0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
ddf0: 6f 6e 20 2d 20 74 68 65 20 70 72 6f 67 72 65 73 on - the progres
de00: 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 s callback - tha
de10: 74 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 t.** is invoked
de20: 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 periodically dur
de30: 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 ing long running
de40: 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
de50: 65 33 5f 65 78 65 63 28 29 5d 2c 0a 2a 2a 20 5b e3_exec()],.** [
de60: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
de70: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 and [sqlite3_get
de80: 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 _table()]. An e
de90: 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 xample use for t
dea0: 68 69 73 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 his .** interfac
deb0: 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 e is to keep a G
dec0: 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e UI updated durin
ded0: 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e g a large query.
dee0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 .**.** The progr
def0: 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ess callback is
df00: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 invoked once for
df10: 20 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c every N virtual
df20: 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 machine opcodes
df30: 2c 0a 2a 2a 20 77 68 65 72 65 20 4e 20 69 73 20 ,.** where N is
df40: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
df50: 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 ent to this func
df60: 74 69 6f 6e 2e 20 54 68 65 20 70 72 6f 67 72 65 tion. The progre
df70: 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 ss callback.** i
df80: 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66 tself is identif
df90: 69 65 64 20 62 79 20 74 68 65 20 74 68 69 72 64 ied by the third
dfa0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 argument to thi
dfb0: 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 s function. The
dfc0: 66 6f 75 72 74 68 0a 2a 2a 20 61 72 67 75 6d 65 fourth.** argume
dfd0: 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 nt to this funct
dfe0: 69 6f 6e 20 69 73 20 61 20 76 6f 69 64 20 70 6f ion is a void po
dff0: 69 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 inter passed to
e000: 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c the progress cal
e010: 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f lback.** functio
e020: 6e 20 65 61 63 68 20 74 69 6d 65 20 69 74 20 69 n each time it i
e030: 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a s invoked..**.**
e040: 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 If a call to [s
e050: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 qlite3_exec()],
e060: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
e070: 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 67 65 , or [sqlite3_ge
e080: 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 72 65 t_table()].** re
e090: 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74 sults in fewer t
e0a0: 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73 20 62 65 han N opcodes be
e0b0: 69 6e 67 20 65 78 65 63 75 74 65 64 2c 20 74 68 ing executed, th
e0c0: 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 en the progress
e0d0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 .** callback is
e0e0: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a never invoked..*
e0f0: 2a 20 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e * .** Only a sin
e100: 67 6c 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c gle progress cal
e110: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d lback function m
e120: 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 ay be registered
e130: 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 6f 70 65 for each.** ope
e140: 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 n database conne
e150: 63 74 69 6f 6e 2e 20 20 45 76 65 72 79 20 63 61 ction. Every ca
e160: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 ll to sqlite3_pr
e170: 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 ogress_handler()
e180: 0a 2a 2a 20 6f 76 65 72 77 72 69 74 65 73 20 74 .** overwrites t
e190: 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20 74 68 he results of th
e1a0: 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e e previous call.
e1b0: 0a 2a 2a 20 54 6f 20 72 65 6d 6f 76 65 20 74 68 .** To remove th
e1c0: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 e progress callb
e1d0: 61 63 6b 20 61 6c 74 6f 67 65 74 68 65 72 2c 20 ack altogether,
e1e0: 70 61 73 73 20 4e 55 4c 4c 20 61 73 20 74 68 65 pass NULL as the
e1f0: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 third.** argume
e200: 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 nt to this funct
e210: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ion..**.** If th
e220: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 e progress callb
e230: 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65 ack returns a re
e240: 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20 sult other than
e250: 30 2c 20 74 68 65 6e 20 74 68 65 20 63 75 72 72 0, then the curr
e260: 65 6e 74 20 0a 2a 2a 20 71 75 65 72 79 20 69 73 ent .** query is
e270: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 74 65 72 immediately ter
e280: 6d 69 6e 61 74 65 64 20 61 6e 64 20 61 6e 79 20 minated and any
e290: 64 61 74 61 62 61 73 65 20 63 68 61 6e 67 65 73 database changes
e2a0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a rolled back..**
e2b0: 20 54 68 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 The containing
e2c0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
e2d0: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
e2e0: 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 )], or.** [sqlit
e2f0: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 e3_get_table()]
e300: 63 61 6c 6c 20 72 65 74 75 72 6e 73 20 53 51 4c call returns SQL
e310: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 2e 20 20 ITE_INTERRUPT.
e320: 20 54 68 69 73 20 66 65 61 74 75 72 65 0a 2a 2a This feature.**
e330: 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 66 6f can be used, fo
e340: 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 69 6d r example, to im
e350: 70 6c 65 6d 65 6e 74 20 74 68 65 20 22 43 61 6e plement the "Can
e360: 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 cel" button on a
e370: 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 64 69 61 .** progress dia
e380: 6c 6f 67 20 62 6f 78 20 69 6e 20 61 20 47 55 49 log box in a GUI
e390: 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
e3a0: 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 3_progress_handl
e3b0: 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 er(sqlite3*, int
e3c0: 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c , int(*)(void*),
e3d0: 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
e3e0: 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e CAPI3REF: Openin
e3f0: 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 g A New Database
e400: 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a Connection.**.*
e410: 2a 20 4f 70 65 6e 20 74 68 65 20 73 71 6c 69 74 * Open the sqlit
e420: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
e430: 22 66 69 6c 65 6e 61 6d 65 22 2e 20 20 54 68 65 "filename". The
e440: 20 22 66 69 6c 65 6e 61 6d 65 22 20 69 73 20 55 "filename" is U
e450: 54 46 2d 38 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 TF-8.** encoded
e460: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e for sqlite3_open
e470: 28 29 20 61 6e 64 20 55 54 46 2d 31 36 20 65 6e () and UTF-16 en
e480: 63 6f 64 65 64 20 69 6e 20 74 68 65 20 6e 61 74 coded in the nat
e490: 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a ive byte order.*
e4a0: 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 * for sqlite3_op
e4b0: 65 6e 31 36 28 29 2e 20 20 41 6e 20 5b 73 71 6c en16(). An [sql
e4c0: 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 69 73 ite3*] handle is
e4d0: 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 returned in *pp
e4e0: 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69 66 20 61 Db, even.** if a
e4f0: 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 n error occurs.
e500: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
e510: 69 73 20 6f 70 65 6e 65 64 20 28 6f 72 20 63 72 is opened (or cr
e520: 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 eated) successfu
e530: 6c 6c 79 2c 0a 2a 2a 20 74 68 65 6e 20 5b 53 51 lly,.** then [SQ
e540: 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 LITE_OK] is retu
e550: 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65 20 rned. Otherwise
e560: 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 an error code is
e570: 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 0a 2a returned. The.*
e580: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 * [sqlite3_errms
e590: 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 g()] or [sqlite3
e5a0: 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 20 72 6f _errmsg16()] ro
e5b0: 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 utines can be us
e5c0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 ed to obtain.**
e5d0: 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 an English langu
e5e0: 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 age description
e5f0: 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a of the error..**
e600: 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 .** If the datab
e610: 61 73 65 20 66 69 6c 65 20 64 6f 65 73 20 6e 6f ase file does no
e620: 74 20 65 78 69 73 74 2c 20 74 68 65 6e 20 61 20 t exist, then a
e630: 6e 65 77 20 64 61 74 61 62 61 73 65 20 77 69 6c new database wil
e640: 6c 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 l be created.**
e650: 61 73 20 6e 65 65 64 65 64 2e 20 20 54 68 65 20 as needed. The
e660: 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 default encoding
e670: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 for the databas
e680: 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 e will be UTF-8
e690: 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 if.** sqlite3_op
e6a0: 65 6e 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 en() is called a
e6b0: 6e 64 20 55 54 46 2d 31 36 20 69 66 20 73 71 6c nd UTF-16 if sql
e6c0: 69 74 65 33 5f 6f 70 65 6e 31 36 20 69 73 20 75 ite3_open16 is u
e6d0: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 sed..**.** Wheth
e6e0: 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 er or not an err
e6f0: 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 or occurs when i
e700: 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 t is opened, res
e710: 6f 75 72 63 65 73 20 61 73 73 6f 63 69 61 74 65 ources associate
e720: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 d.** with the [s
e730: 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 qlite3*] handle
e740: 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 should be releas
e750: 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 ed by passing it
e760: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
e770: 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 close()] when it
e780: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 is no longer re
e790: 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 quired..**.** Th
e7a0: 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 e sqlite3_open_v
e7b0: 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 2() interface wo
e7c0: 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 rks like sqlite3
e7d0: 5f 6f 70 65 6e 28 29 20 65 78 63 65 70 74 20 74 _open() except t
e7e0: 68 61 74 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 hat.** provides
e7f0: 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 two additional p
e800: 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 arameters for ad
e810: 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c ditional control
e820: 20 6f 76 65 72 20 74 68 65 0a 2a 2a 20 6e 65 77 over the.** new
e830: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
e840: 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 tion. The flags
e850: 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 parameter can b
e860: 65 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 e one of:.**.**
e870: 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 <ol>.** <li> [S
e880: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
e890: 4e 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NLY].** <li> [S
e8a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
e8b0: 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RITE].** <li> [
e8c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
e8d0: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 WRITE] | [SQLITE
e8e0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 0a 2a 2a _OPEN_CREATE].**
e8f0: 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 </ol>.**.** The
e900: 20 66 69 72 73 74 20 76 61 6c 75 65 20 6f 70 65 first value ope
e910: 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ns the database
e920: 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 49 66 20 74 read-only. If t
e930: 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 he database does
e940: 0a 2a 2a 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 .** not previous
e950: 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 ly exist, an err
e960: 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 or is returned.
e970: 20 54 68 65 20 73 65 63 6f 6e 64 20 6f 70 74 69 The second opti
e980: 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 74 68 65 20 on opens.** the
e990: 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 database for rea
e9a0: 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 ding and writing
e9b0: 20 62 75 74 20 74 68 65 20 64 61 74 61 62 61 73 but the databas
e9c0: 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 0a 2a e must already.*
e9d0: 2a 20 65 78 69 73 74 20 6f 72 20 61 6e 20 65 72 * exist or an er
e9e0: 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ror is returned.
e9f0: 20 20 54 68 65 20 74 68 69 72 64 20 6f 70 74 69 The third opti
ea00: 6f 6e 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74 on opens the dat
ea10: 61 62 61 73 65 0a 2a 2a 20 66 6f 72 20 72 65 61 abase.** for rea
ea20: 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 ding and writing
ea30: 20 61 6e 64 20 63 72 65 61 74 65 73 20 69 74 20 and creates it
ea40: 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 if it does not a
ea50: 6c 72 65 61 64 79 20 65 78 69 73 74 2e 0a 2a 2a lready exist..**
ea60: 20 54 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f The third optio
ea70: 6e 73 20 69 73 20 62 65 68 61 76 69 6f 72 20 74 ns is behavior t
ea80: 68 61 74 20 69 73 20 75 73 65 64 20 61 6c 77 61 hat is used alwa
ea90: 79 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f ys for sqlite3_o
eaa0: 70 65 6e 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c pen().** and sql
eab0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 0a 2a ite3_open16()..*
eac0: 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 *.** The fourth
ead0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
eae0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
eaf0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
eb00: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 e.** [sqlite3_vf
eb10: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 s] object that d
eb20: 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 efines the opera
eb30: 74 69 6e 67 20 73 79 73 74 65 6d 20 0a 2a 2a 20 ting system .**
eb40: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74 interface that t
eb50: 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 he new database
eb60: 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c connection shoul
eb70: 64 20 75 73 65 2e 20 20 49 66 20 74 68 65 0a 2a d use. If the.*
eb80: 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 * fourth paramet
eb90: 65 72 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 er is a NULL poi
eba0: 6e 74 65 72 20 74 68 65 6e 20 61 20 64 65 66 61 nter then a defa
ebb0: 75 6c 74 20 73 75 69 74 61 62 6c 65 20 66 6f 72 ult suitable for
ebc0: 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 65 6e 76 .** the host env
ebd0: 69 72 6f 6e 6d 65 6e 74 20 69 73 20 73 75 62 73 ironment is subs
ebe0: 74 69 74 75 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e tituted..**.** N
ebf0: 6f 74 65 20 74 6f 20 77 69 6e 64 6f 77 73 20 75 ote to windows u
ec00: 73 65 72 73 3a 20 20 54 68 65 20 65 6e 63 6f 64 sers: The encod
ec10: 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 ing used for the
ec20: 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
ec30: 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 nt.** of sqlite3
ec40: 5f 6f 70 65 6e 28 29 20 6d 75 73 74 20 62 65 20 _open() must be
ec50: 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 UTF-8, not whate
ec60: 76 65 72 20 63 6f 64 65 70 61 67 65 20 69 73 20 ver codepage is
ec70: 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 64 65 66 currently.** def
ec80: 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 ined. Filenames
ec90: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 containing inte
eca0: 72 6e 61 74 69 6f 6e 61 6c 20 63 68 61 72 61 63 rnational charac
ecb0: 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e ters must be con
ecc0: 76 65 72 74 65 64 0a 2a 2a 20 74 6f 20 55 54 46 verted.** to UTF
ecd0: 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 -8 prior to pass
ece0: 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 20 73 71 ing them into sq
ecf0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2f lite3_open()..*/
ed00: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 .int sqlite3_ope
ed10: 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 n(. const char
ed20: 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
ed30: 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
ed40: 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 e (UTF-8) */. s
ed50: 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 qlite3 **ppDb
ed60: 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 /* OUT: S
ed70: 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 QLite db handle
ed80: 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 */.);.int sqlite
ed90: 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 3_open16(. cons
eda0: 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 t void *filename
edb0: 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
edc0: 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 filename (UTF-16
edd0: 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a ) */. sqlite3 *
ede0: 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f *ppDb /
edf0: 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 * OUT: SQLite db
ee00: 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e handle */.);.in
ee10: 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 t sqlite3_open_v
ee20: 32 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2(. const void
ee30: 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
ee40: 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
ee50: 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 e (UTF-8) */. s
ee60: 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 qlite3 **ppDb,
ee70: 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 /* OUT: S
ee80: 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 QLite db handle
ee90: 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 */. int flags,
eea0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
eeb0: 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 Flags */. const
eec0: 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 char *zVfs
eed0: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 /* Name of VF
eee0: 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 S module to use
eef0: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
ef00: 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 I3REF: Error Cod
ef10: 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a es And Messages.
ef20: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
ef30: 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 3_errcode() inte
ef40: 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
ef50: 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b 53 51 e numeric.** [SQ
ef60: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 LITE_OK | result
ef70: 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54 code] or [SQLIT
ef80: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 E_IOERR_READ | e
ef90: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
efa0: 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 ode].** for the
efb0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c most recent fail
efc0: 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 ed sqlite3_* API
efd0: 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 call associated
efe0: 0a 2a 2a 20 77 69 74 68 20 5b 73 71 6c 69 74 65 .** with [sqlite
eff0: 33 5d 20 68 61 6e 64 6c 65 20 27 64 62 27 2e 20 3] handle 'db'.
f000: 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 If a prior API
f010: 63 61 6c 6c 20 66 61 69 6c 65 64 20 62 75 74 20 call failed but
f020: 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 the.** most rece
f030: 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 nt API call succ
f040: 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 eeded, the retur
f050: 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c n value from sql
f060: 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a ite3_errcode().*
f070: 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 * is undefined.
f080: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
f090: 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 e3_errmsg() and
f0a0: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
f0b0: 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 () return Englis
f0c0: 68 2d 6c 61 6e 67 61 75 67 65 0a 2a 2a 20 74 65 h-langauge.** te
f0d0: 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 xt that describe
f0e0: 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 s the error, as
f0f0: 65 69 74 68 65 72 20 55 54 46 38 20 6f 72 20 55 either UTF8 or U
f100: 54 46 31 36 20 72 65 73 70 65 63 74 69 76 65 6c TF16 respectivel
f110: 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 y..** Memory to
f120: 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d hold the error m
f130: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 essage string is
f140: 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 managed interna
f150: 6c 6c 79 2e 20 20 54 68 65 20 0a 2a 2a 20 73 74 lly. The .** st
f160: 72 69 6e 67 20 6d 61 79 20 62 65 20 6f 76 65 72 ring may be over
f170: 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c written or deall
f180: 6f 63 61 74 65 64 20 62 79 20 73 75 62 73 65 71 ocated by subseq
f190: 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 53 51 uent calls to SQ
f1a0: 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 Lite.** interfac
f1b0: 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a e functions..**.
f1c0: 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 6d 61 6e 79 ** Calls to many
f1d0: 20 73 71 6c 69 74 65 33 5f 2a 20 66 75 6e 63 74 sqlite3_* funct
f1e0: 69 6f 6e 73 20 73 65 74 20 74 68 65 20 65 72 72 ions set the err
f1f0: 6f 72 20 63 6f 64 65 20 61 6e 64 20 73 74 72 69 or code and stri
f200: 6e 67 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 ng returned.** b
f210: 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f y [sqlite3_errco
f220: 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f de()], [sqlite3_
f230: 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b errmsg()], and [
f240: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
f250: 28 29 5d 0a 2a 2a 20 28 6f 76 65 72 77 72 69 74 ()].** (overwrit
f260: 69 6e 67 20 74 68 65 20 70 72 65 76 69 6f 75 73 ing the previous
f270: 20 76 61 6c 75 65 73 29 2e 20 4e 6f 74 65 20 74 values). Note t
f280: 68 61 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 hat calls to [sq
f290: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
f2a0: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 ,.** [sqlite3_er
f2b0: 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 rmsg()], and [sq
f2c0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
f2d0: 5d 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 ] themselves do
f2e0: 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 0a 2a not affect the.*
f2f0: 2a 20 72 65 73 75 6c 74 73 20 6f 66 20 66 75 74 * results of fut
f300: 75 72 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e ure invocations.
f310: 20 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 Calls to API r
f320: 6f 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20 outines that do
f330: 6e 6f 74 20 72 65 74 75 72 6e 0a 2a 2a 20 61 6e not return.** an
f340: 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61 error code (exa
f350: 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 mple: [sqlite3_d
f360: 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f ata_count()]) do
f370: 20 6e 6f 74 0a 2a 2a 20 63 68 61 6e 67 65 20 74 not.** change t
f380: 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 72 65 he error code re
f390: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 turned by this r
f3a0: 6f 75 74 69 6e 65 2e 20 20 49 6e 74 65 72 66 61 outine. Interfa
f3b0: 63 65 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 ces that are.**
f3c0: 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 not associated w
f3d0: 69 74 68 20 61 20 73 70 65 63 69 66 69 63 20 64 ith a specific d
f3e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
f3f0: 6f 6e 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a on (examples:.**
f400: 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 [sqlite3_mprint
f410: 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 f()] or [sqlite3
f420: 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 _enable_shared_c
f430: 61 63 68 65 28 29 5d 20 64 6f 20 6e 6f 74 20 63 ache()] do not c
f440: 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 hange.** the ret
f450: 75 72 6e 20 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a urn code. .**.*
f460: 2a 20 41 73 73 75 6d 69 6e 67 20 6e 6f 20 6f 74 * Assuming no ot
f470: 68 65 72 20 69 6e 74 65 72 76 65 6e 69 6e 67 20 her intervening
f480: 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 sqlite3_* API ca
f490: 6c 6c 73 20 61 72 65 20 6d 61 64 65 2c 20 74 68 lls are made, th
f4a0: 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 e error.** code
f4b0: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 returned by this
f4c0: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 73 73 function is ass
f4d0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
f4e0: 20 73 61 6d 65 20 65 72 72 6f 72 20 61 73 0a 2a same error as.*
f4f0: 2a 20 74 68 65 20 73 74 72 69 6e 67 73 20 72 65 * the strings re
f500: 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
f510: 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 e3_errmsg()] and
f520: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
f530: 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 16()]..*/.int sq
f540: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 lite3_errcode(sq
f550: 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 lite3 *db);.cons
f560: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
f570: 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 errmsg(sqlite3*)
f580: 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
f590: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 lite3_errmsg16(s
f5a0: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
f5b0: 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 CAPI3REF: SQL S
f5c0: 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a tatement Object.
f5d0: 2a 2a 0a 2a 2a 20 49 6e 73 74 61 6e 63 65 20 6f **.** Instance o
f5e0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 f this object re
f5f0: 70 72 65 73 65 6e 74 20 73 69 6e 67 6c 65 20 53 present single S
f600: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 QL statements.
f610: 54 68 69 73 0a 2a 2a 20 69 73 20 76 61 72 69 6f This.** is vario
f620: 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 usly known as a
f630: 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d "prepared statem
f640: 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20 22 63 ent" or a .** "c
f650: 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 ompiled SQL stat
f660: 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 ement" or simply
f670: 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 as a "statement
f680: 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c 69 "..** .** The li
f690: 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e fe of a statemen
f6a0: 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f t object goes so
f6b0: 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 mething like thi
f6c0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a s:.**.** <ol>.**
f6d0: 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 <li> Create the
f6e0: 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 object using [s
f6f0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
f700: 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 2()] or a relate
f710: 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 d.** functi
f720: 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 on..** <li> Bind
f730: 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 values to host
f740: 70 61 72 61 6d 65 74 65 72 73 20 75 73 69 6e 67 parameters using
f750: 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 .** [sqlite
f760: 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 3_bind_blob | sq
f770: 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69 6e 74 lite3_bind_* int
f780: 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c 69 erfaces]..** <li
f790: 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 > Run the SQL by
f7a0: 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
f7b0: 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 3_step()] one or
f7c0: 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 more times..**
f7d0: 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 <li> Reset the s
f7e0: 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b tatement using [
f7f0: 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
f800: 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a then go back.**
f810: 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e to step 2.
f820: 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f Do this zero o
f830: 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a r more times..**
f840: 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 <li> Destroy th
f850: 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b e object using [
f860: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
f870: 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a ()]..** </ol>.**
f880: 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 .** Refer to doc
f890: 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e umentation on in
f8a0: 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 dividual methods
f8b0: 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 above for addit
f8c0: 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 ional.** informa
f8d0: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 tion..*/.typedef
f8e0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
f8f0: 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d stmt sqlite3_stm
f900: 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 t;../*.** CAPI3R
f910: 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e EF: Compiling An
f920: 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a SQL Statement.*
f930: 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 *.** To execute
f940: 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 an SQL query, it
f950: 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 must first be c
f960: 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 ompiled into a b
f970: 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 yte-code.** prog
f980: 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 ram using one of
f990: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e these routines.
f9a0: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 .**.** The firs
f9b0: 74 20 61 72 67 75 6d 65 6e 74 20 22 64 62 22 20 t argument "db"
f9c0: 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 20 7c is an [sqlite3 |
f9d0: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 SQLite database
f9e0: 20 68 61 6e 64 6c 65 5d 20 0a 2a 2a 20 6f 62 74 handle] .** obt
f9f0: 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 ained from a pri
fa00: 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 or call to [sqli
fa10: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b te3_open()] or [
fa20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
fa30: 5d 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 ]..** The second
fa40: 20 61 72 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22 argument "zSql"
fa50: 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e is the statemen
fa60: 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
fa70: 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 , encoded.** as
fa80: 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
fa90: 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c UTF-16. The sql
faa0: 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 ite3_prepare() a
fab0: 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
fac0: 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 re_v2().** inter
fad0: 66 61 63 65 73 20 75 73 65 73 20 55 54 46 2d 38 faces uses UTF-8
fae0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
faf0: 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c pare16() and sql
fb00: 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
fb10: 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 2().** use UTF-1
fb20: 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6..**.** If the
fb30: 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 nByte argument i
fb40: 73 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a s less.** than z
fb50: 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 ero, then zSql i
fb60: 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 s read up to the
fb70: 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d first zero term
fb80: 69 6e 61 74 6f 72 2e 20 20 49 66 0a 2a 2a 20 6e inator. If.** n
fb90: 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 Byte is non-nega
fba0: 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 tive, then it is
fbb0: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d the maximum num
fbc0: 62 65 72 20 6f 66 20 0a 2a 2a 20 62 79 74 65 73 ber of .** bytes
fbd0: 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e read from zSql.
fbe0: 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 When nByte is
fbf0: 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 non-negative, th
fc00: 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 e.** zSql string
fc10: 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 ends at either
fc20: 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 the first '\000'
fc30: 20 63 68 61 72 61 63 74 65 72 20 6f 72 20 0a 2a character or .*
fc40: 2a 20 75 6e 74 69 6c 20 74 68 65 20 6e 42 79 74 * until the nByt
fc50: 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 e-th byte, which
fc60: 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 ever comes first
fc70: 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 ..**.** *pzTail
fc80: 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 is made to point
fc90: 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 to the first by
fca0: 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 te past the end
fcb0: 6f 66 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 of the first.**
fcc0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
fcd0: 20 7a 53 71 6c 2e 20 20 54 68 69 73 20 72 6f 75 zSql. This rou
fce0: 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c tine only compil
fcf0: 65 73 20 74 68 65 20 66 69 72 73 74 20 73 74 61 es the first sta
fd00: 74 65 6d 65 6e 74 0a 2a 2a 20 69 6e 20 7a 53 71 tement.** in zSq
fd10: 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 l, so *pzTail is
fd20: 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 left pointing t
fd30: 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 o what remains u
fd40: 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a ncompiled..**.**
fd50: 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 *ppStmt is left
fd60: 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 pointing to a c
fd70: 6f 6d 70 69 6c 65 64 20 0a 2a 2a 20 5b 73 71 6c ompiled .** [sql
fd80: 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20 ite3_stmt | SQL
fd90: 73 74 61 74 65 6d 65 6e 74 20 73 74 72 75 63 74 statement struct
fda0: 75 72 65 5d 20 74 68 61 74 20 63 61 6e 20 62 65 ure] that can be
fdb0: 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 .** executed usi
fdc0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ng [sqlite3_step
fdd0: 28 29 5d 2e 20 20 4f 72 20 69 66 20 74 68 65 72 ()]. Or if ther
fde0: 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a e is an error, *
fdf0: 70 70 53 74 6d 74 20 6d 61 79 20 62 65 0a 2a 2a ppStmt may be.**
fe00: 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 set to NULL. I
fe10: 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 f the input text
fe20: 20 63 6f 6e 74 61 69 6e 65 64 20 6e 6f 20 53 51 contained no SQ
fe30: 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 L (if the input
fe40: 69 73 20 61 6e 64 0a 2a 2a 20 65 6d 70 74 79 20 is and.** empty
fe50: 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d string or a comm
fe60: 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d ent) then *ppStm
fe70: 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c t is set to NULL
fe80: 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 0a 2a . The calling.*
fe90: 2a 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 * procedure is r
fea0: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 esponsible for d
feb0: 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 eleting the comp
fec0: 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 iled SQL stateme
fed0: 6e 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c nt.** using [sql
fee0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
fef0: 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 after it has fi
ff00: 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a nished with it..
ff10: 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 **.** On success
ff20: 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 , [SQLITE_OK] is
ff30: 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 returned. Othe
ff40: 72 77 69 73 65 20 61 6e 20 0a 2a 2a 20 5b 53 51 rwise an .** [SQ
ff50: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 LITE_ERROR | err
ff60: 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
ff70: 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rned..**.** The
ff80: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
ff90: 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 v2() and sqlite3
ffa0: 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 _prepare16_v2()
ffb0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a interfaces are.*
ffc0: 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f * recommended fo
ffd0: 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 r all new progra
ffe0: 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 ms. The two olde
fff0: 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 r interfaces are
10000 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 retained.** for
10010 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
10020 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 tibility, but th
10030 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f eir use is disco
10040 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 uraged..** In th
10050 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
10060 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 s, the prepared
10070 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 statement.** tha
10080 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 t is returned (t
10090 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
100a0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 ] object) contai
100b0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 ns a copy of the
100c0 20 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 .** original SQ
100d0 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 L text. This cau
100e0 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ses the [sqlite3
100f0 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 _step()] interfa
10100 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 ce to.** behave
10110 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e a differently in
10120 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a two ways:.**.**
10130 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a <ol>.** <li>.**
10140 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 If the database
10150 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c schema changes,
10160 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 instead of retu
10170 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 rning [SQLITE_SC
10180 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 HEMA] as it.** a
10190 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f lways used to do
101a0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
101b0 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 )] will automati
101c0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 cally recompile
101d0 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 the SQL.** state
101e0 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 ment and try to
101f0 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 run it again. I
10200 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 f the schema has
10210 20 63 68 61 6e 67 65 64 20 69 6e 20 61 20 77 61 changed in a wa
10220 79 0a 2a 2a 20 74 68 61 74 20 6d 61 6b 65 73 20 y.** that makes
10230 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f the statement no
10240 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b longer valid, [
10250 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
10260 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 will still.** re
10270 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 turn [SQLITE_SCH
10280 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b EMA]. But unlik
10290 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 e the legacy beh
102a0 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 avior, [SQLITE_S
102b0 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 CHEMA] is.** now
102c0 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 a fatal error.
102d0 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 Calling [sqlite
102e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
102f0 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d again will not m
10300 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 ake the.** error
10310 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a go away. Note:
10320 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 use [sqlite3_er
10330 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 rmsg()] to find
10340 74 68 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 the text of the
10350 70 61 72 73 69 6e 67 0a 2a 2a 20 65 72 72 6f 72 parsing.** error
10360 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e that results in
10370 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 an [SQLITE_SCHE
10380 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c MA] return..** <
10390 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a /li>.**.** <li>.
103a0 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 ** When an error
103b0 20 6f 63 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 occurs, .** [sq
103c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
103d0 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 ll return one of
103e0 20 74 68 65 20 64 65 74 61 69 6c 65 64 20 0a 2a the detailed .*
103f0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 * [SQLITE_ERROR
10400 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 | result codes]
10410 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f or.** [SQLITE_IO
10420 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e ERR_READ | exten
10430 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
10440 5d 20 73 75 63 68 20 61 73 20 64 69 72 65 63 74 ] such as direct
10450 6c 79 2e 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63 ly..** The legac
10460 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 y behavior was t
10470 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 hat [sqlite3_ste
10480 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 p()] would only
10490 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 return a generic
104a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f .** [SQLITE_ERRO
104b0 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 R] result code a
104c0 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 nd you would hav
104d0 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f e to make a seco
104e0 6e 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 nd call to.** [s
104f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
10500 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 in order to find
10510 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 the underlying
10520 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f cause of the pro
10530 62 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 blem..** With th
10540 65 20 22 76 32 22 20 70 72 65 70 61 72 65 20 69 e "v2" prepare i
10550 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 nterfaces, the u
10560 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e nderlying reason
10570 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 for the error i
10580 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6d s.** returned im
10590 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f mediately..** </
105a0 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a li>.** </ol>.*/.
105b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
105c0 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a are(. sqlite3 *
105d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
105e0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
105f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
10600 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
10610 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
10620 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
10630 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
10640 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
10650 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
10660 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
10670 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
10680 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
10690 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
106a0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
106b0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
106c0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
106d0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
106e0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
106f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
10700 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c repare_v2(. sql
10710 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
10720 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
10730 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
10740 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
10750 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
10760 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 ement, UTF-8 enc
10770 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
10780 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
10790 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
107a0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
107b0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
107c0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
107d0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
107e0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
107f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a const char **pz
10800 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
10810 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
10820 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
10830 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c ql */.);.int sql
10840 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a ite3_prepare16(.
10850 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
10860 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
10870 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
10880 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 const void *zS
10890 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
108a0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
108b0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 16 encoded */.
108c0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
108d0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
108e0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
108f0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
10900 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
10910 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
10920 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
10930 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
10940 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f d **pzTail /
10950 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
10960 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
10970 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 of zSql */.);.i
10980 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
10990 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 re16_v2(. sqlit
109a0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
109b0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
109c0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
109d0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 void *zSql,
109e0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
109f0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f ent, UTF-16 enco
10a00 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
10a10 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
10a20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
10a30 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
10a40 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
10a50 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
10a60 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
10a70 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
10a80 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 const void **pzT
10a90 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
10aa0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
10ab0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
10ac0 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 l */.);../*.** C
10ad0 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61 6d 69 API3REF: Dynami
10ae0 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 cally Typed Valu
10af0 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 53 e Object.**.** S
10b00 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d QLite uses dynam
10b10 69 63 20 74 79 70 69 6e 67 20 66 6f 72 20 74 68 ic typing for th
10b20 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 e values it stor
10b30 65 73 2e 20 20 56 61 6c 75 65 73 20 63 61 6e 20 es. Values can
10b40 0a 2a 2a 20 62 65 20 69 6e 74 65 67 65 72 73 2c .** be integers,
10b50 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
10b60 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c values, strings,
10b70 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e BLOBs, or NULL.
10b80 20 20 57 68 65 6e 0a 2a 2a 20 70 61 73 73 69 6e When.** passin
10b90 67 20 61 72 6f 75 6e 64 20 76 61 6c 75 65 73 20 g around values
10ba0 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 65 61 63 68 internally, each
10bb0 20 76 61 6c 75 65 20 69 73 20 72 65 70 72 65 73 value is repres
10bc0 65 6e 74 65 64 20 61 73 0a 2a 2a 20 61 6e 20 69 ented as.** an i
10bd0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 nstance of the s
10be0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
10bf0 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ect..*/.typedef
10c00 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 struct Mem sqlit
10c10 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a e3_value;../*.**
10c20 20 43 41 50 49 33 52 45 46 3a 20 20 53 51 4c 20 CAPI3REF: SQL
10c30 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 Function Context
10c40 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 Object.**.** Th
10c50 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 e context in whi
10c60 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 ch an SQL functi
10c70 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 on executes is s
10c80 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 tored in an.** s
10c90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f qlite3_context o
10ca0 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 bject. A pointe
10cb0 72 20 74 6f 20 73 75 63 68 20 61 6e 20 6f 62 6a r to such an obj
10cc0 65 63 74 20 69 73 20 74 68 65 0a 2a 2a 20 66 69 ect is the.** fi
10cd0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
10ce0 20 75 73 65 72 2d 64 65 66 69 6e 65 64 20 53 51 user-defined SQ
10cf0 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a L functions..*/.
10d00 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
10d10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 qlite3_context s
10d20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a qlite3_context;.
10d30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
10d40 20 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 Binding Values
10d50 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 To Prepared Sta
10d60 74 65 6d 65 6e 74 73 0a 2a 2a 0a 2a 2a 20 49 6e tements.**.** In
10d70 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 the SQL strings
10d80 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 input to [sqlit
10d90 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
10da0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 and its variant
10db0 73 2c 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 s,.** one or mor
10dc0 65 20 6c 69 74 65 72 61 6c 73 20 63 61 6e 20 62 e literals can b
10dd0 65 20 72 65 70 6c 61 63 65 20 62 79 20 61 20 70 e replace by a p
10de0 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 arameter in one
10df0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 66 6f 72 6d of these.** form
10e00 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
10e10 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e <li> ?.** <li>
10e20 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 ?NNN.** <li>
10e30 3a 41 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 40 41 :AAA.** <li> @A
10e40 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 AA.** <li> $VVV
10e50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
10e60 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 In the parameter
10e70 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f forms shown abo
10e80 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 ve NNN is an int
10e90 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a eger literal,.**
10ea0 20 41 41 41 20 69 73 20 61 6e 20 61 6c 70 68 61 AAA is an alpha
10eb0 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 numeric identifi
10ec0 65 72 20 61 6e 64 20 56 56 56 20 69 73 20 61 20 er and VVV is a
10ed0 76 61 72 69 61 62 6c 65 20 6e 61 6d 65 20 61 63 variable name ac
10ee0 63 6f 72 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 cording.** to th
10ef0 65 20 73 79 6e 74 61 78 20 72 75 6c 65 73 20 6f e syntax rules o
10f00 66 20 74 68 65 20 54 43 4c 20 70 72 6f 67 72 61 f the TCL progra
10f10 6d 6d 69 6e 67 20 6c 61 6e 67 75 61 67 65 2e 0a mming language..
10f20 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 ** The values of
10f30 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 these parameter
10f40 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 s (also called "
10f50 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e host parameter n
10f60 61 6d 65 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 ames").** can be
10f70 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 set using the s
10f80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
10f90 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 routines defined
10fa0 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 here..**.** The
10fb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
10fc0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 to the sqlite3_b
10fd0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 ind_*() routines
10fe0 20 61 6c 77 61 79 73 20 69 73 20 61 20 70 6f 69 always is a poi
10ff0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b nter.** to the [
11000 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 sqlite3_stmt] ob
11010 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 ject returned fr
11020 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 om [sqlite3_prep
11030 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 are_v2()] or.**
11040 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 54 its variants. T
11050 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 he second.** arg
11060 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 ument is the ind
11070 65 78 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 ex of the parame
11080 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 20 20 ter to be set.
11090 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
110a0 74 65 72 20 68 61 73 0a 2a 2a 20 61 6e 20 69 6e ter has.** an in
110b0 64 65 78 20 6f 66 20 31 2e 20 57 68 65 6e 20 74 dex of 1. When t
110c0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 20 70 61 he same named pa
110d0 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 rameter is used
110e0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 more than once,
110f0 73 65 63 6f 6e 64 0a 2a 2a 20 61 6e 64 20 73 75 second.** and su
11100 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 bsequent.** occu
11110 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 rrences have the
11120 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 same index as t
11130 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 he first occurre
11140 6e 63 65 2e 20 20 54 68 65 20 69 6e 64 65 78 20 nce. The index
11150 66 6f 72 0a 2a 2a 20 6e 61 6d 65 64 20 70 61 72 for.** named par
11160 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c ameters can be l
11170 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 ooked up using t
11180 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 he.** [sqlite3_b
11190 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
111a0 6d 65 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 me()] API if des
111b0 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 ired. The index
111c0 20 66 6f 72 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 70 for "?NNN".** p
111d0 61 72 61 6d 65 74 65 73 20 69 73 20 74 68 65 20 arametes is the
111e0 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a value of NNN..**
111f0 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d The NNN value m
11200 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 ust be between 1
11210 20 61 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 and the compile
11220 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74 -time.** paramet
11230 65 72 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 er SQLITE_MAX_VA
11240 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64 RIABLE_NUMBER (d
11250 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 efault value: 99
11260 39 29 2e 0a 2a 2a 20 53 65 65 20 3c 61 20 68 72 9)..** See <a hr
11270 65 66 3d 22 6c 69 6d 69 74 73 2e 68 74 6d 6c 22 ef="limits.html"
11280 3e 6c 69 6d 69 74 73 2e 68 74 6d 6c 3c 2f 61 3e >limits.html</a>
11290 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
112a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
112b0 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 ** The third arg
112c0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c ument is the val
112d0 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 ue to bind to th
112e0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a e parameter..**.
112f0 2a 2a 20 49 6e 20 74 68 6f 73 65 0a 2a 2a 20 72 ** In those.** r
11300 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 outines that hav
11310 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d e a fourth argum
11320 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 ent, its value i
11330 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
11340 62 79 74 65 73 0a 2a 2a 20 69 6e 20 74 68 65 20 bytes.** in the
11350 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 parameter. To b
11360 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c e clear: the val
11370 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 ue is the number
11380 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
11390 0a 2a 2a 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 .** string, not
113a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 the number of ch
113b0 61 72 61 63 74 65 72 73 2e 20 20 54 68 65 20 6e aracters. The n
113c0 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 umber.** of byte
113d0 73 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 s does not inclu
113e0 64 65 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d de the zero-term
113f0 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e inator at the en
11400 64 20 6f 66 20 73 74 72 69 6e 67 73 2e 0a 2a 2a d of strings..**
11410 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 If the fourth p
11420 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 arameter is nega
11430 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 tive, the length
11440 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 of the string i
11450 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 s.** number of b
11460 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 ytes up to the f
11470 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e irst zero termin
11480 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ator..**.** The
11490 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 fifth argument t
114a0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 o sqlite3_bind_b
114b0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 lob(), sqlite3_b
114c0 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a ind_text(), and.
114d0 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f ** sqlite3_bind_
114e0 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 text16() is a de
114f0 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f structor used to
11500 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 dispose of the
11510 42 4c 4f 42 20 6f 72 0a 2a 2a 20 74 65 78 74 20 BLOB or.** text
11520 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 after SQLite has
11530 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 finished with i
11540 74 2e 20 20 49 66 20 74 68 65 20 66 69 66 74 68 t. If the fifth
11550 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
11560 0a 2a 2a 20 73 70 65 63 69 61 6c 20 76 61 6c 75 .** special valu
11570 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 e [SQLITE_STATIC
11580 5d 2c 20 74 68 65 6e 20 74 68 65 20 6c 69 62 72 ], then the libr
11590 61 72 79 20 61 73 73 75 6d 65 73 20 74 68 61 74 ary assumes that
115a0 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e the information
115b0 0a 2a 2a 20 69 73 20 69 6e 20 73 74 61 74 69 63 .** is in static
115c0 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 , unmanaged spac
115d0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e e and does not n
115e0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e eed to be freed.
115f0 20 20 49 66 20 74 68 65 0a 2a 2a 20 66 69 66 74 If the.** fift
11600 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 h argument has t
11610 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 he value [SQLITE
11620 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 _TRANSIENT], the
11630 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 n SQLite makes i
11640 74 73 0a 2a 2a 20 6f 77 6e 20 70 72 69 76 61 74 ts.** own privat
11650 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 e copy of the da
11660 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 ta immediately,
11670 62 65 66 6f 72 65 20 74 68 65 20 73 71 6c 69 74 before the sqlit
11680 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 72 e3_bind_*().** r
11690 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a outine returns..
116a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
116b0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 3_bind_zeroblob(
116c0 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 ) routine binds
116d0 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 a BLOB of length
116e0 20 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 n that.** is fi
116f0 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 73 2e lled with zeros.
11700 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 A zeroblob use
11710 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 s a fixed amount
11720 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a of memory.** (j
11730 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 ust an integer t
11740 6f 20 68 6f 6c 64 20 69 74 20 73 69 7a 65 29 20 o hold it size)
11750 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e while it is bein
11760 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 g processed..**
11770 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e Zeroblobs are in
11780 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 tended to serve
11790 61 73 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 as place-holders
117a0 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 for BLOBs whose
117b0 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c .** content is l
117c0 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 ater written usi
117d0 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ng .** [sqlite3_
117e0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 blob_open | incr
117f0 65 6d 65 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d 20 ement BLOB I/O]
11800 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
11810 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 The sqlite3_bind
11820 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 _*() routines mu
11830 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 st be called aft
11840 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 er.** [sqlite3_p
11850 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e repare_v2()] (an
11860 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 d its variants)
11870 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 or [sqlite3_rese
11880 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f t()] and.** befo
11890 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 re [sqlite3_step
118a0 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 ()]..** Bindings
118b0 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 are not cleared
118c0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 by the [sqlite3
118d0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e _reset()] routin
118e0 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 e..** Unbound pa
118f0 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 rameters are int
11900 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c erpreted as NULL
11910 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
11920 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 utines return [S
11930 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
11940 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 cess or an error
11950 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 code if.** anyt
11960 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e hing goes wrong.
11970 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d [SQLITE_RANGE]
11980 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 is returned if
11990 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a the parameter.**
119a0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 index is out of
119b0 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 range. [SQLITE
119c0 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 _NOMEM] is retur
119d0 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 20 66 61 ned if malloc fa
119e0 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ils..** [SQLITE_
119f0 4d 49 53 55 53 45 5d 20 69 73 20 72 65 74 75 72 MISUSE] is retur
11a00 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 ned if these rou
11a10 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
11a20 20 6f 6e 20 61 20 76 69 72 74 75 61 6c 0a 2a 2a on a virtual.**
11a30 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 machine that is
11a40 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 the wrong state
11a50 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c or which has al
11a60 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c ready been final
11a70 69 7a 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ized..*/.int sql
11a80 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 ite3_bind_blob(s
11a90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
11aa0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 t, const void*,
11ab0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 int n, void(*)(v
11ac0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 oid*));.int sqli
11ad0 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 te3_bind_double(
11ae0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
11af0 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 nt, double);.int
11b00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e sqlite3_bind_in
11b10 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
11b20 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 int, int);.int
11b30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 sqlite3_bind_int
11b40 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 64(sqlite3_stmt*
11b50 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 , int, sqlite3_i
11b60 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 nt64);.int sqlit
11b70 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c e3_bind_null(sql
11b80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 ite3_stmt*, int)
11b90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
11ba0 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f nd_text(sqlite3_
11bb0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
11bc0 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 t char*, int n,
11bd0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
11be0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
11bf0 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 d_text16(sqlite3
11c00 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
11c10 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 st void*, int, v
11c20 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
11c30 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
11c40 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 _value(sqlite3_s
11c50 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
11c60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 sqlite3_value*)
11c70 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
11c80 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 nd_zeroblob(sqli
11c90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
11ca0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int n);../*.** C
11cb0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
11cc0 4f 66 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 Of Host Paramete
11cd0 72 73 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 rs.**.** Return
11ce0 74 68 65 20 6c 61 72 67 65 73 74 20 68 6f 73 74 the largest host
11cf0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 65 78 parameter index
11d00 20 69 6e 20 74 68 65 20 70 72 65 63 6f 6d 70 69 in the precompi
11d10 6c 65 64 20 73 74 61 74 65 6d 65 6e 74 20 67 69 led statement gi
11d20 76 65 6e 0a 2a 2a 20 61 73 20 74 68 65 20 61 72 ven.** as the ar
11d30 67 75 6d 65 6e 74 2e 20 20 57 68 65 6e 20 74 68 gument. When th
11d40 65 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 e host parameter
11d50 73 20 61 72 65 20 6f 66 20 74 68 65 20 66 6f 72 s are of the for
11d60 6d 73 20 6c 69 6b 65 20 22 3a 41 41 41 22 0a 2a ms like ":AAA".*
11d70 2a 20 6f 72 20 22 3f 22 2c 20 74 68 65 6e 20 74 * or "?", then t
11d80 68 65 79 20 61 72 65 20 61 73 73 69 67 6e 65 64 hey are assigned
11d90 20 73 65 71 75 65 6e 74 69 61 6c 20 69 6e 63 72 sequential incr
11da0 65 61 73 69 6e 67 20 6e 75 6d 62 65 72 73 20 62 easing numbers b
11db0 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 77 69 74 68 eginning.** with
11dc0 20 6f 6e 65 2c 20 73 6f 20 74 68 65 20 76 61 6c one, so the val
11dd0 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 ue returned is t
11de0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 he number of par
11df0 61 6d 65 74 65 72 73 2e 20 20 48 6f 77 65 76 65 ameters. Howeve
11e00 72 0a 2a 2a 20 69 66 20 74 68 65 20 73 61 6d 65 r.** if the same
11e10 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 host parameter
11e20 6e 61 6d 65 20 69 73 20 75 73 65 64 20 6d 75 6c name is used mul
11e30 74 69 70 6c 65 20 74 69 6d 65 73 2c 20 65 61 63 tiple times, eac
11e40 68 20 6f 63 63 75 72 72 61 6e 63 65 0a 2a 2a 20 h occurrance.**
11e50 69 73 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d is given the sam
11e60 65 20 6e 75 6d 62 65 72 2c 20 73 6f 20 74 68 65 e number, so the
11e70 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
11e80 69 6e 20 74 68 61 74 20 63 61 73 65 20 69 73 20 in that case is
11e90 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 the number.** of
11ea0 20 75 6e 69 71 75 65 20 68 6f 73 74 20 70 61 72 unique host par
11eb0 61 6d 65 74 65 72 20 6e 61 6d 65 73 2e 20 20 49 ameter names. I
11ec0 66 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 f host parameter
11ed0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f s of the form "?
11ee0 4e 4e 4e 22 0a 2a 2a 20 61 72 65 20 75 73 65 64 NNN".** are used
11ef0 20 28 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 (where NNN is a
11f00 6e 20 69 6e 74 65 67 65 72 29 20 74 68 65 6e 20 n integer) then
11f10 74 68 65 72 65 20 6d 69 67 68 74 20 62 65 20 67 there might be g
11f20 61 70 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6e 75 aps in the.** nu
11f30 6d 62 65 72 69 6e 67 20 61 6e 64 20 74 68 65 20 mbering and the
11f40 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
11f50 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 y this interface
11f60 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
11f70 20 74 68 65 0a 2a 2a 20 68 6f 73 74 20 70 61 72 the.** host par
11f80 61 6d 65 74 65 72 20 77 69 74 68 20 74 68 65 20 ameter with the
11f90 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 76 61 largest index va
11fa0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 lue..**.** The p
11fb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
11fc0 74 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 5b 73 t must not be [s
11fd0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 qlite3_finalize
11fe0 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 0a 2a 2a 20 | finalized].**
11ff0 70 72 69 6f 72 20 74 6f 20 74 68 69 73 20 72 6f prior to this ro
12000 75 74 69 6e 65 20 72 65 74 75 72 6e 6e 69 6e 67 utine returnning
12010 2e 20 20 4f 74 68 65 72 77 69 73 65 20 74 68 65 . Otherwise the
12020 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
12030 65 66 69 6e 65 64 0a 2a 2a 20 61 6e 64 20 70 72 efined.** and pr
12040 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 obably undesirab
12050 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 le..*/.int sqlit
12060 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
12070 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f r_count(sqlite3_
12080 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
12090 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 API3REF: Name Of
120a0 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 A Host Paramete
120b0 72 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 r.**.** This rou
120c0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 tine returns a p
120d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 ointer to the na
120e0 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 20 70 me of the n-th p
120f0 61 72 61 6d 65 74 65 72 20 69 6e 20 61 20 0a 2a arameter in a .*
12100 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 * [sqlite3_stmt
12110 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 | prepared state
12120 6d 65 6e 74 5d 2e 0a 2a 2a 20 48 6f 73 74 20 70 ment]..** Host p
12130 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
12140 20 66 6f 72 6d 20 22 3a 41 41 41 22 20 6f 72 20 form ":AAA" or
12150 22 40 41 41 41 22 20 6f 72 20 22 24 56 56 56 22 "@AAA" or "$VVV"
12160 20 68 61 76 65 20 61 20 6e 61 6d 65 0a 2a 2a 20 have a name.**
12170 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 which is the str
12180 69 6e 67 20 22 3a 41 41 41 22 20 6f 72 20 22 40 ing ":AAA" or "@
12190 41 41 41 22 20 6f 72 20 22 24 56 56 56 22 2e 20 AAA" or "$VVV".
121a0 20 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f .** In other wo
121b0 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c rds, the initial
121c0 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 ":" or "$" or "
121d0 40 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 @".** is include
121e0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 d as part of the
121f0 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 name..** Parame
12200 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d ters of the form
12210 20 22 3f 22 20 6f 72 20 22 3f 4e 4e 4e 22 20 68 "?" or "?NNN" h
12220 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a ave no name..**.
12230 2a 2a 20 54 68 65 20 66 69 72 73 74 20 62 6f 75 ** The first bou
12240 6e 64 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 nd parameter has
12250 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 an index of 1,
12260 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 not 0..**.** If
12270 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f the value n is o
12280 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 ut of range or i
12290 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d f the n-th param
122a0 65 74 65 72 20 69 73 20 6e 61 6d 65 6c 65 73 73 eter is nameless
122b0 2c 0a 2a 2a 20 74 68 65 6e 20 4e 55 4c 4c 20 69 ,.** then NULL i
122c0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 s returned. The
122d0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
122e0 20 69 73 20 61 6c 77 61 79 73 20 69 6e 20 74 68 is always in th
122f0 65 0a 2a 2a 20 55 54 46 2d 38 20 65 6e 63 6f 64 e.** UTF-8 encod
12300 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 ing even if the
12310 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 named parameter
12320 77 61 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 was originally s
12330 70 65 63 69 66 69 65 64 0a 2a 2a 20 61 73 20 55 pecified.** as U
12340 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 TF-16 in [sqlite
12350 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 3_prepare16()] o
12360 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
12370 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 re16_v2()]..*/.c
12380 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
12390 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
123a0 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 r_name(sqlite3_s
123b0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a tmt*, int);../*.
123c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 ** CAPI3REF: Ind
123d0 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 ex Of A Paramete
123e0 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e r With A Given N
123f0 61 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 ame.**.** This r
12400 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
12410 68 65 20 69 6e 64 65 78 20 6f 66 20 61 20 68 6f he index of a ho
12420 73 74 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 st parameter wit
12430 68 20 74 68 65 20 67 69 76 65 6e 20 6e 61 6d 65 h the given name
12440 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6d 75 ..** The name mu
12450 73 74 20 6d 61 74 63 68 20 65 78 61 63 74 6c 79 st match exactly
12460 2e 20 20 49 66 20 6e 6f 20 70 61 72 61 6d 65 74 . If no paramet
12470 65 72 20 77 69 74 68 20 74 68 65 20 67 69 76 65 er with the give
12480 6e 20 6e 61 6d 65 20 69 73 20 0a 2a 2a 20 66 6f n name is .** fo
12490 75 6e 64 2c 20 72 65 74 75 72 6e 20 30 2e 20 20 und, return 0.
124a0 50 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 20 Parameter names
124b0 6d 75 73 74 20 62 65 20 55 54 46 38 2e 0a 2a 2f must be UTF8..*/
124c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
124d0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
124e0 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c x(sqlite3_stmt*,
124f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
12500 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 me);../*.** CAPI
12510 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 3REF: Reset All
12520 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 Bindings On A Pr
12530 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
12540 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 .**.** Contrary
12550 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e to the intuition
12560 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 of many, [sqlit
12570 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 e3_reset()] does
12580 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74 20 74 68 not.** reset th
12590 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
125a0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d blob | bindings]
125b0 20 6f 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 on a .** [sqlit
125c0 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 e3_stmt | prepar
125d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 ed statement].
125e0 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 Use this routine
125f0 20 74 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c 6c to.** reset all
12600 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 host parameters
12610 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 to NULL..*/.int
12620 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 sqlite3_clear_b
12630 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f indings(sqlite3_
12640 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
12650 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
12660 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 Of Columns In A
12670 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a Result Set.**.**
12680 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 Return the numb
12690 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
126a0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
126b0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 returned by the
126c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d .** [sqlite3_stm
126d0 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c t | compiled SQL
126e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 statement]. Thi
126f0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
12700 73 20 30 0a 2a 2a 20 69 66 20 70 53 74 6d 74 20 s 0.** if pStmt
12710 69 73 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d is an SQL statem
12720 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f ent that does no
12730 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 t return data (f
12740 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 61 or .** example a
12750 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2f 0a 69 6e n UPDATE)..*/.in
12760 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
12770 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 _count(sqlite3_s
12780 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
12790 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
127a0 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 lumn Names In A
127b0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a Result Set.**.**
127c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
127d0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 return the name
127e0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 assigned to a pa
127f0 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a rticular column.
12800 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ** in the result
12810 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 set of a SELECT
12820 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 statement. The
12830 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
12840 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 name().** interf
12850 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
12860 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 38 20 inter to a UTF8
12870 73 74 72 69 6e 67 20 61 6e 64 20 73 71 6c 69 74 string and sqlit
12880 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
12890 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 ().** returns a
128a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 pointer to a UTF
128b0 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 16 string. The
128c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
128d0 69 73 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 is the.** [sqlit
128e0 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 e3_stmt | prepar
128f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
12900 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 at implements th
12910 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 e SELECT stateme
12920 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e nt..** The secon
12930 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
12940 68 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 he column number
12950 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 . The left-most
12960 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75 column is.** nu
12970 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 mber 0..**.** Th
12980 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
12990 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c g pointer is val
129a0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 id until either
129b0 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the .** [sqlite3
129c0 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 _stmt | prepared
129d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 statement] is d
129e0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c estroyed by [sql
129f0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
12a00 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 .** or until the
12a10 20 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c 69 74 next call sqlit
12a20 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
12a30 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
12a40 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 6f mn_name16().** o
12a50 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d n the same colum
12a60 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 n..**.** If sqli
12a70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 te3_malloc() fai
12a80 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 ls during the pr
12a90 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 ocessing of eith
12aa0 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 er routine.** (f
12ab0 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e or example durin
12ac0 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 g a conversion f
12ad0 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 rom UTF-8 to UTF
12ae0 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e -16) then a.** N
12af0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
12b00 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 eturned..*/.cons
12b10 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
12b20 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 column_name(sqli
12b30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e te3_stmt*, int N
12b40 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
12b50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
12b60 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
12b70 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a t*, int N);../*.
12b80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 ** CAPI3REF: Sou
12b90 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 rce Of Data In A
12ba0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a Query Result.**
12bb0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
12bc0 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 es provide a mea
12bd0 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 ns to determine
12be0 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 what column of w
12bf0 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 hat.** table in
12c00 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61 which database a
12c10 20 72 65 73 75 6c 74 20 6f 66 20 61 20 53 45 4c result of a SEL
12c20 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 63 6f ECT statement co
12c30 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 mes from..** The
12c40 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
12c50 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f abase or table o
12c60 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 r column can be
12c70 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 returned as.** e
12c80 69 74 68 65 72 20 61 20 55 54 46 38 20 6f 72 20 ither a UTF8 or
12c90 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54 UTF16 string. T
12ca0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f he _database_ ro
12cb0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a utines return.**
12cc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 the database na
12cd0 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 me, the _table_
12ce0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
12cf0 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 the table name,
12d00 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 and.** the origi
12d10 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 n_ routines retu
12d20 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 rn the column na
12d30 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 me..** The retur
12d40 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 ned string is va
12d50 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a 20 74 68 65 lid until.** the
12d60 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c [sqlite3_stmt |
12d70 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
12d80 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 ent] is destroye
12d90 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 d using.** [sqli
12da0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
12db0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d or until the sam
12dc0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 e information is
12dd0 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 requested.** ag
12de0 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 ain in a differe
12df0 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a nt encoding..**.
12e00 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65 74 ** The names ret
12e10 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 urned are the or
12e20 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 iginal un-aliase
12e30 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a d names of the.*
12e40 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c * database, tabl
12e50 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a e, and column..*
12e60 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
12e70 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 rgument to the f
12e80 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 ollowing calls i
12e90 73 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s a .** [sqlite3
12ea0 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 _stmt | compiled
12eb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e SQL statement].
12ec0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
12ed0 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 ons return infor
12ee0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 mation about the
12ef0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 Nth column retu
12f00 72 6e 65 64 20 62 79 20 0a 2a 2a 20 74 68 65 20 rned by .** the
12f10 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 statement, where
12f20 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 N is the second
12f30 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
12f40 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 nt..**.** If the
12f50 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 Nth column retu
12f60 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 rned by the stat
12f70 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 ement is an expr
12f80 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 ession.** or sub
12f90 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 query and is not
12fa0 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c a column value,
12fb0 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 then all of the
12fc0 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 se functions.**
12fd0 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 20 4f 74 68 return NULL. Oth
12fe0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 erwise, they ret
12ff0 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65 urn the .** name
13000 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 of the attached
13010 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
13020 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 and column that
13030 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a query result.**
13040 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 column was extr
13050 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a acted from..**.*
13060 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 * As with all ot
13070 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c her SQLite APIs,
13080 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64 those postfixed
13090 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 with "16" retur
130a0 6e 20 55 54 46 2d 31 36 0a 2a 2a 20 65 6e 63 6f n UTF-16.** enco
130b0 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65 ded strings, the
130c0 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 other functions
130d0 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a return UTF-8..*
130e0 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 *.** These APIs
130f0 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 are only availab
13100 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 le if the librar
13110 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 y was compiled w
13120 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 ith the .** SQLI
13130 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e TE_ENABLE_COLUMN
13140 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f _METADATA prepro
13150 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 cessor symbol de
13160 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 fined..**.** If
13170 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
13180 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
13190 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f more of these ro
131a0 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 utines against t
131b0 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 he same.** prepa
131c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e red statement an
131d0 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 d column at the
131e0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 same time then t
131f0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a he results are.*
13200 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a * undefined..*/.
13210 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
13220 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
13230 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ase_name(sqlite3
13240 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
13250 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
13260 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
13270 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
13280 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
13290 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
132a0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d column_table_nam
132b0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
132c0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 int);.const void
132d0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
132e0 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 _table_name16(sq
132f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
13300 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 ;.const char *sq
13310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 lite3_column_ori
13320 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 gin_name(sqlite3
13330 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
13340 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
13350 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e _column_origin_n
13360 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
13370 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a mt*,int);../*.**
13380 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 CAPI3REF: Decla
13390 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 red Datatype Of
133a0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a A Query Result.*
133b0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 *.** The first p
133c0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 73 arameter is a [s
133d0 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f qlite3_stmt | co
133e0 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 mpiled SQL state
133f0 6d 65 6e 74 5d 2e 20 0a 2a 2a 20 49 66 20 74 68 ment]. .** If th
13400 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 is statement is
13410 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 a SELECT stateme
13420 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 nt and the Nth c
13430 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 0a 2a 2a olumn of the .**
13440 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 returned result
13450 20 73 65 74 20 20 6f 66 20 74 68 61 74 20 53 45 set of that SE
13460 4c 45 43 54 20 69 73 20 61 20 74 61 62 6c 65 20 LECT is a table
13470 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a column (not an.*
13480 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 * expression or
13490 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 subquery) then t
134a0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 he declared type
134b0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a of the table.**
134c0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 column is retur
134d0 6e 65 64 2e 20 49 66 20 74 68 65 20 4e 74 68 20 ned. If the Nth
134e0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 column of the re
134f0 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a sult set is an.*
13500 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 * expression or
13510 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 subquery, then a
13520 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 NULL pointer is
13530 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 returned..** Th
13540 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
13550 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d g is always UTF-
13560 38 20 65 6e 63 6f 64 65 64 2e 20 46 6f 72 20 65 8 encoded. For e
13570 78 61 6d 70 6c 65 2c 20 69 6e 0a 2a 2a 20 74 68 xample, in.** th
13580 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
13590 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 a:.**.** CREATE
135a0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 TABLE t1(c1 VARI
135b0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20 ANT);.**.** And
135c0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 the following st
135d0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64 atement compiled
135e0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 :.**.** SELECT c
135f0 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 1 + 1, c1 FROM t
13600 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68 1;.**.** Then th
13610 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 is routine would
13620 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 return the stri
13630 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 ng "VARIANT" for
13640 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 the second.** r
13650 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d esult column (i=
13660 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 =1), and a NULL
13670 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 pointer for the
13680 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c first result col
13690 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a umn.** (i==0)..*
136a0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 *.** SQLite uses
136b0 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d dynamic run-tim
136c0 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 e typing. So ju
136d0 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c st because a col
136e0 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 umn.** is declar
136f0 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 ed to contain a
13700 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 particular type
13710 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 does not mean th
13720 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 at the.** data s
13730 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f tored in that co
13740 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 lumn is of the d
13750 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 eclared type. S
13760 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f QLite is.** stro
13770 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 ngly typed, but
13780 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 the typing is dy
13790 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 namic not static
137a0 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 . Type.** is as
137b0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e sociated with in
137c0 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c dividual values,
137d0 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f not with the co
137e0 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 ntainers.** used
137f0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 to hold those v
13800 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 alues..*/.const
13810 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
13820 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 lumn_decltype(sq
13830 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2c 20 69 6e lite3_stmt *, in
13840 74 20 69 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 t i);.const void
13850 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
13860 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 _decltype16(sqli
13870 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
13880 0a 2f 2a 20 0a 2a 2a 20 43 41 50 49 33 52 45 46 ./* .** CAPI3REF
13890 3a 20 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 : Evaluate An S
138a0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a QL Statement.**.
138b0 2a 2a 20 41 66 74 65 72 20 61 6e 20 5b 73 71 6c ** After an [sql
138c0 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20 ite3_stmt | SQL
138d0 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 statement] has b
138e0 65 65 6e 20 70 72 65 70 61 72 65 64 20 77 69 74 een prepared wit
138f0 68 20 61 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65 h a call.** to e
13900 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 ither [sqlite3_p
13910 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
13920 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
13930 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 6f 20 6f 16_v2()] or to o
13940 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 65 67 ne of.** the leg
13950 61 63 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b acy interfaces [
13960 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
13970 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
13980 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 repare16()],.**
13990 74 68 65 6e 20 74 68 69 73 20 66 75 6e 63 74 69 then this functi
139a0 6f 6e 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 on must be calle
139b0 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 d one or more ti
139c0 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 mes to evaluate
139d0 74 68 65 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e the .** statemen
139e0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 t..**.** The det
139f0 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 ails of the beha
13a00 76 69 6f 72 20 6f 66 20 74 68 69 73 20 73 71 6c vior of this sql
13a10 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 ite3_step() inte
13a20 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 rface depend.**
13a30 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 on whether the s
13a40 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 tatement was pre
13a50 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 pared using the
13a60 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 newer "v2" inter
13a70 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 face.** [sqlite3
13a80 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
13a90 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
13aa0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 are16_v2()] or t
13ab0 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a he older legacy.
13ac0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 ** interface [sq
13ad0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
13ae0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
13af0 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 epare16()]. The
13b00 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e use of the.** n
13b10 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 ew "v2" interfac
13b20 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 e is recommended
13b30 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 for new applica
13b40 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 tions but the le
13b50 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
13b60 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 e will continue
13b70 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e to be supported.
13b80 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 61 .**.** In the la
13b90 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 gacy interface,
13ba0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
13bb0 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 will be either
13bc0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 0a [SQLITE_BUSY], .
13bd0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d ** [SQLITE_DONE]
13be0 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 , [SQLITE_ROW],
13bf0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 [SQLITE_ERROR],
13c00 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 or [SQLITE_MISUS
13c10 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 E]..** With the
13c20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 "v2" interface,
13c30 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 any of the other
13c40 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 [SQLITE_OK | re
13c50 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72 sult code].** or
13c60 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 [SQLITE_IOERR_R
13c70 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 EAD | extended r
13c80 65 73 75 6c 74 20 63 6f 64 65 5d 20 6d 69 67 68 esult code] migh
13c90 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 t be returned as
13ca0 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 .** well..**.**
13cb0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 [SQLITE_BUSY] me
13cc0 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 ans that the dat
13cd0 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 abase engine was
13ce0 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 unable to acqui
13cf0 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 re the.** databa
13d00 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 se locks it need
13d10 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e s to do its job.
13d20 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 If the stateme
13d30 6e 74 20 69 73 20 61 20 43 4f 4d 4d 49 54 0a 2a nt is a COMMIT.*
13d40 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 * or occurs outs
13d50 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 ide of an explic
13d60 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 it transaction,
13d70 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 then you can ret
13d80 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d ry the.** statem
13d90 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 ent. If the sta
13da0 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 tement is not a
13db0 43 4f 4d 4d 49 54 20 61 6e 64 20 6f 63 63 75 72 COMMIT and occur
13dc0 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 s within a.** ex
13dd0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 plicit transacti
13de0 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 on then you shou
13df0 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 ld rollback the
13e00 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f transaction befo
13e10 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 re.** continuing
13e20 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ..**.** [SQLITE_
13e30 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 DONE] means that
13e40 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 the statement h
13e50 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 as finished exec
13e60 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 uting.** success
13e70 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f fully. sqlite3_
13e80 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f step() should no
13e90 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 t be called agai
13ea0 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 n on this virtua
13eb0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 l.** machine wit
13ec0 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 hout first calli
13ed0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
13ee0 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 t()] to reset th
13ef0 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 e virtual.** mac
13f00 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 hine back to its
13f10 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a initial state..
13f20 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c **.** If the SQL
13f30 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 statement being
13f40 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e executed return
13f50 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e s any data, then
13f60 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 .** [SQLITE_ROW
13f70 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 ] is returned ea
13f80 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f ch time a new ro
13f90 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 w of data is rea
13fa0 64 79 0a 2a 2a 20 66 6f 72 20 70 72 6f 63 65 73 dy.** for proces
13fb0 73 69 6e 67 20 62 79 20 74 68 65 20 63 61 6c 6c sing by the call
13fc0 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d er. The values m
13fd0 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 ay be accessed u
13fe0 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c sing.** the [sql
13ff0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 ite3_column_int
14000 7c 20 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 | column access
14010 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 functions]..** s
14020 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 qlite3_step() is
14030 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f called again to
14040 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 retrieve the ne
14050 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a xt row of data..
14060 2a 2a 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 ** .** [SQLITE_E
14070 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 RROR] means that
14080 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f a run-time erro
14090 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e r (such as a con
140a0 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 straint.** viola
140b0 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 tion) has occurr
140c0 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 ed. sqlite3_ste
140d0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 p() should not b
140e0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f e called again o
140f0 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 n.** the VM. Mor
14100 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 e information ma
14110 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 y be found by ca
14120 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 lling [sqlite3_e
14130 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 rrmsg()]..** Wit
14140 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 h the legacy int
14150 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 erface, a more s
14160 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f pecific error co
14170 64 65 20 28 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20 de (example:.**
14180 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 [SQLITE_INTERRUP
14190 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 T], [SQLITE_SCHE
141a0 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 MA], [SQLITE_COR
141b0 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f RUPT], and so fo
141c0 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f rth).** can be o
141d0 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 btained by calli
141e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
141f0 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b t()] on the.** [
14200 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 sqlite3_stmt | p
14210 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
14220 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 t]. In the "v2"
14230 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 interface,.** t
14240 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 he more specific
14250 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 error code is r
14260 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 eturned directly
14270 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 by sqlite3_step
14280 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 ()..**.** [SQLIT
14290 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 E_MISUSE] means
142a0 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f that the this ro
142b0 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 utine was called
142c0 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 inappropriately
142d0 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 ..** Perhaps it
142e0 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 was called on a
142f0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 [sqlite3_stmt |
14300 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
14310 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 nt] that has.**
14320 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 already been [sq
14330 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c lite3_finalize |
14340 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f finalized] or o
14350 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 20 0a n one that had .
14360 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 ** previously re
14370 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 turned [SQLITE_E
14380 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 RROR] or [SQLITE
14390 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 _DONE]. Or it c
143a0 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 ould.** be the c
143b0 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d ase that the sam
143c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
143d0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 ction is being u
143e0 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a sed by two or.**
143f0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 more threads at
14400 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 the same moment
14410 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 in time..**.**
14420 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 <b>Goofy Interfa
14430 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a ce Alert:</b>.**
14440 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 In the legacy i
14450 6e 74 65 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68 nterface, .** th
14460 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 e sqlite3_step()
14470 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 API always retu
14480 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 rns a generic er
14490 72 6f 72 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51 ror code,.** [SQ
144a0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c LITE_ERROR], fol
144b0 6c 6f 77 69 6e 67 20 61 6e 79 20 65 72 72 6f 72 lowing any error
144c0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
144d0 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64 ITE_BUSY].** and
144e0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
144f0 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c . You must call
14500 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
14510 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
14520 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 3_finalize()] in
14530 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f order to find o
14540 6e 65 20 6f 66 20 74 68 65 20 73 70 65 63 69 66 ne of the specif
14550 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 ic.** [SQLITE_ER
14560 52 4f 52 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 ROR | result cod
14570 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 es] that better
14580 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 describes the er
14590 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 ror..** We admit
145a0 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 that this is a
145b0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 goofy design. T
145c0 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 he problem has b
145d0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 een fixed.** wit
145e0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 h the "v2" inter
145f0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 face. If you pr
14600 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 epare all of you
14610 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 r SQL statements
14620 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 .** using either
14630 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
14640 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 e_v2()] or [sqli
14650 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
14660 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f ()] instead.** o
14670 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 f the legacy [sq
14680 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
14690 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
146a0 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e epare16()], then
146b0 20 74 68 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70 the .** more sp
146c0 65 63 69 66 69 63 20 5b 53 51 4c 49 54 45 5f 45 ecific [SQLITE_E
146d0 52 52 4f 52 20 7c 20 72 65 73 75 6c 74 20 63 6f RROR | result co
146e0 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 des] are returne
146f0 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 d directly.** by
14700 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e sqlite3_step().
14710 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 The use of the
14720 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 "v2" interface
14730 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a is recommended..
14740 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 */.int sqlite3_s
14750 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 tep(sqlite3_stmt
14760 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
14770 52 45 46 3a 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 REF:.**.** Retur
14780 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 n the number of
14790 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 values in the cu
147a0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 rrent row of the
147b0 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a result set..**.
147c0 2a 2a 20 41 66 74 65 72 20 61 20 63 61 6c 6c 20 ** After a call
147d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
147e0 28 29 5d 20 74 68 61 74 20 72 65 74 75 72 6e 73 ()] that returns
147f0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 [SQLITE_ROW], t
14800 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 77 his routine.** w
14810 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 73 ill return the s
14820 61 6d 65 20 76 61 6c 75 65 20 61 73 20 74 68 65 ame value as the
14830 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
14840 5f 63 6f 75 6e 74 28 29 5d 20 66 75 6e 63 74 69 _count()] functi
14850 6f 6e 2e 0a 2a 2a 20 41 66 74 65 72 20 5b 73 71 on..** After [sq
14860 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 lite3_step()] ha
14870 73 20 72 65 74 75 72 6e 65 64 20 61 6e 20 5b 53 s returned an [S
14880 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 QLITE_DONE], [SQ
14890 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 0a 2a LITE_BUSY], or.*
148a0 2a 20 61 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f * a [SQLITE_ERRO
148b0 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 2c R | error code],
148c0 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 or before [sqli
148d0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
148e0 62 65 65 6e 20 0a 2a 2a 20 63 61 6c 6c 65 64 20 been .** called
148f0 6f 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f on the [sqlite3_
14900 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 stmt | prepared
14910 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72 20 74 statement] for t
14920 68 65 20 66 69 72 73 74 20 74 69 6d 65 2c 0a 2a he first time,.*
14930 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 * this routine r
14940 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a eturns zero..*/.
14950 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 int sqlite3_data
14960 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 _count(sqlite3_s
14970 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
14980 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 .** CAPI3REF: Fu
14990 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 ndamental Dataty
149a0 70 65 73 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 pes.**.** Every
149b0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 value in SQLite
149c0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 has one of five
149d0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 fundamental data
149e0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c types:.**.** <ul
149f0 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 >.** <li> 64-bit
14a00 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a signed integer.
14a10 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 ** <li> 64-bit I
14a20 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 EEE floating poi
14a30 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 nt number.** <li
14a40 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e > string.** <li>
14a50 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 BLOB.** <li> NU
14a60 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a LL.** </ul>.**.*
14a70 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
14a80 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 s are codes for
14a90 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 each of those ty
14aa0 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 pes..**.** Note
14ab0 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f that the SQLITE_
14ac0 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 TEXT constant wa
14ad0 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 s also used in S
14ae0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a QLite version 2.
14af0 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 ** for a complet
14b00 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 ely different me
14b10 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 aning. Software
14b20 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 that links agai
14b30 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 nst both.** SQLi
14b40 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 te version 2 and
14b50 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
14b60 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 3 should use SQL
14b70 49 54 45 33 5f 54 45 58 54 20 6e 6f 74 0a 2a 2a ITE3_TEXT not.**
14b80 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f SQLITE_TEXT..*/
14b90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
14ba0 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 INTEGER 1.#defi
14bb0 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 ne SQLITE_FLOAT
14bc0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
14bd0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 ITE_BLOB 4.#
14be0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 define SQLITE_NU
14bf0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 LL 5.#ifdef
14c00 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e SQLITE_TEXT.# un
14c10 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a def SQLITE_TEXT.
14c20 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 #else.# define S
14c30 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 QLITE_TEXT 3
14c40 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 .#endif.#define
14c50 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 SQLITE3_TEXT
14c60 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 3../*.** CAPI3R
14c70 45 46 3a 20 52 65 73 75 6c 74 73 20 56 61 6c 75 EF: Results Valu
14c80 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a es From A Query.
14c90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
14ca0 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f ines return info
14cb0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 0a 2a 2a rmation about.**
14cc0 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e a single column
14cd0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 of the current
14ce0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 result row of a
14cf0 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 query. In every
14d00 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 66 69 72 .** case the fir
14d10 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 st argument is a
14d20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
14d30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d .** [sqlite3_stm
14d40 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e t | SQL statemen
14d50 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 t] that is being
14d60 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 28 74 .** evaluated (t
14d70 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
14d80 2a 5d 20 74 68 61 74 20 77 61 73 20 72 65 74 75 *] that was retu
14d90 72 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 rned from .** [s
14da0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
14db0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 2()] or one of i
14dc0 74 73 20 76 61 72 69 61 6e 74 73 29 20 61 6e 64 ts variants) and
14dd0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 61 .** the second a
14de0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 rgument is the i
14df0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 ndex of the colu
14e00 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 mn for which inf
14e10 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f ormation .** sho
14e20 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e uld be returned.
14e30 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 The left-most
14e40 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 column of the re
14e50 73 75 6c 74 20 73 65 74 0a 2a 2a 20 68 61 73 20 sult set.** has
14e60 61 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a 2a an index of 0..*
14e70 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 *.** If the SQL
14e80 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 statement is not
14e90 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 currently point
14ea0 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c to a valid row,
14eb0 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 or if the.** th
14ec0 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 e column index i
14ed0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 s out of range,
14ee0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e the result is un
14ef0 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 20 54 68 65 defined. .** The
14f00 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 se routines may
14f10 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 only be called w
14f20 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 hen the most rec
14f30 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ent call to.** [
14f40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
14f50 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 has returned [SQ
14f60 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 LITE_ROW] and ne
14f70 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 ither.** [sqlite
14f80 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 3_reset()] nor [
14f90 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
14fa0 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c ()] has been cal
14fb0 6c 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a l subsequently..
14fc0 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 ** If any of the
14fd0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
14fe0 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 called after [sq
14ff0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
15000 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 r.** [sqlite3_fi
15010 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 nalize()] or aft
15020 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 er [sqlite3_step
15030 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 ()] has returned
15040 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 .** something ot
15050 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
15060 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c _ROW], the resul
15070 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
15080 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 ..** If [sqlite3
15090 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c _step()] or [sql
150a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
150b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
150c0 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c ze()].** are cal
150d0 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 led from a diffe
150e0 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c rent thread whil
150f0 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 e any of these r
15100 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 outines.** are p
15110 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 ending, then the
15120 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
15130 65 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 efined. .**.**
15140 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 The sqlite3_colu
15150 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e mn_type() routin
15160 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 e returns .** [S
15170 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 QLITE_INTEGER |
15180 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 datatype code] f
15190 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 or the initial d
151a0 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 ata type.** of t
151b0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e he result column
151c0 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 . The returned
151d0 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 value is one of
151e0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d [SQLITE_INTEGER]
151f0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f ,.** [SQLITE_FLO
15200 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 AT], [SQLITE_TEX
15210 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 T], [SQLITE_BLOB
15220 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 ], or [SQLITE_NU
15230 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a LL]. The value.
15240 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ** returned by s
15250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
15260 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 pe() is only mea
15270 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 ningful if no ty
15280 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e pe.** conversion
15290 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 s have occurred
152a0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c as described bel
152b0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 ow. After a typ
152c0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a e conversion,.**
152d0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
152e0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
152f0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
15300 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 undefined. Futu
15310 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f re.** versions o
15320 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 f SQLite may cha
15330 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 nge the behavior
15340 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 of sqlite3_colu
15350 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c mn_type().** fol
15360 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f lowing a type co
15370 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 nversion..**.**
15380 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
15390 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 a BLOB or UTF-8
153a0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 string then the
153b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
153c0 62 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74 bytes() .** rout
153d0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
153e0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
153f0 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 in that BLOB or
15400 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 string..** If th
15410 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 e result is a UT
15420 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 F-16 string, the
15430 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e n sqlite3_column
15440 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 _bytes() convert
15450 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 s.** the string
15460 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 to UTF-8 and the
15470 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
15480 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a mber of bytes..*
15490 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 * If the result
154a0 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c is a numeric val
154b0 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ue then sqlite3_
154c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 column_bytes() u
154d0 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ses.** [sqlite3_
154e0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 snprintf()] to c
154f0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 onvert that valu
15500 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 e to a UTF-8 str
15510 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a ing and returns.
15520 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
15530 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 bytes in that s
15540 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 tring..** The va
15550 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 lue returned doe
15560 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 s not include th
15570 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f e zero terminato
15580 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 r at the end.**
15590 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 of the string.
155a0 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 For clarity: the
155b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
155c0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
155d0 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 .** bytes in the
155e0 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 string, not the
155f0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 number of chara
15600 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 cters..**.** The
15610 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
15620 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e bytes16() routin
15630 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 e is similar to
15640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
15650 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 ytes().** but le
15660 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 aves the result
15670 69 6e 20 55 54 46 2d 31 36 20 69 6e 73 74 65 61 in UTF-16 instea
15680 64 20 6f 66 20 55 54 46 2d 38 2e 20 20 0a 2a 2a d of UTF-8. .**
15690 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e The zero termin
156a0 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c ator is not incl
156b0 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 uded in this cou
156c0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 nt..**.** These
156d0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 routines attempt
156e0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
156f0 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 value where appr
15700 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a opriate. For.**
15710 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 example, if the
15720 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 internal repres
15730 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 entation is FLOA
15740 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 T and a text res
15750 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 ult.** is reques
15760 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e ted, [sqlite3_sn
15770 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 printf()] is use
15780 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 d internally to
15790 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f do the conversio
157a0 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c n.** automatical
157b0 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 ly. The followi
157c0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 ng table details
157d0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 the conversions
157e0 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 70 70 that.** are app
157f0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lied:.**.** <blo
15800 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 ckquote>.** <tab
15810 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a le border="1">.*
15820 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 * <tr><th> Inter
15830 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e nal<br>Type <th>
15840 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 Requested<br>Ty
15850 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 pe <th> Convers
15860 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 ion.**.** <tr><t
15870 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
15880 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
15890 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c Result is 0.** <
158a0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
158b0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
158c0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 <td> Result is 0
158d0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 .0.** <tr><td>
158e0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 NULL <td> T
158f0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 EXT <td> Resu
15900 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 lt is NULL point
15910 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 er.** <tr><td>
15920 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 NULL <td> B
15930 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 LOB <td> Resu
15940 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 lt is NULL point
15950 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 er.** <tr><td> I
15960 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c NTEGER <td> FL
15970 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 OAT <td> Conv
15980 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 ert from integer
15990 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 to float.** <tr
159a0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c ><td> INTEGER <
159b0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 td> TEXT <t
159c0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 d> ASCII renderi
159d0 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 ng of the intege
159e0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e r.** <tr><td> IN
159f0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c TEGER <td> BL
15a00 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 OB <td> Same
15a10 61 73 20 66 6f 72 20 49 4e 54 45 47 45 52 2d 3e as for INTEGER->
15a20 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e TEXT.** <tr><td>
15a30 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 FLOAT <td> I
15a40 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f NTEGER <td> Co
15a50 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 nvert from float
15a60 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c to integer.** <
15a70 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 tr><td> FLOAT
15a80 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
15a90 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 <td> ASCII rende
15aa0 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 ring of the floa
15ab0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 t.** <tr><td> F
15ac0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c LOAT <td> BL
15ad0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 OB <td> Same
15ae0 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a as FLOAT->TEXT.*
15af0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
15b00 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
15b10 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 <td> Use atoi
15b20 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ().** <tr><td>
15b30 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c TEXT <td> FL
15b40 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 OAT <td> Use
15b50 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 atof().** <tr><t
15b60 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
15b70 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
15b80 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 No change.** <tr
15b90 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c ><td> BLOB <
15ba0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
15bb0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 d> Convert to TE
15bc0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 XT then use atoi
15bd0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ().** <tr><td>
15be0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c BLOB <td> FL
15bf0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 OAT <td> Conv
15c00 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e ert to TEXT then
15c10 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c use atof().** <
15c20 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 tr><td> BLOB
15c30 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
15c40 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 <td> Add a zero
15c50 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 terminator if ne
15c60 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e eded.** </table>
15c70 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 .** </blockquote
15c80 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c >.**.** The tabl
15c90 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 e above makes re
15ca0 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 ference to stand
15cb0 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 ard C library fu
15cc0 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a nctions atoi().*
15cd0 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 * and atof(). S
15ce0 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 QLite does not r
15cf0 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 eally use these
15d00 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 functions. It h
15d10 61 73 20 69 74 73 0a 2a 2a 20 6f 6e 20 65 71 75 as its.** on equ
15d20 61 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c avalent internal
15d30 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 routines. The
15d40 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 atoi() and atof(
15d50 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 ) names are.** u
15d60 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 sed in the table
15d70 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 for brevity and
15d80 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 because they ar
15d90 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f e familiar to mo
15da0 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d st.** C programm
15db0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 ers..**.** Note
15dc0 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 that when type c
15dd0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 onversions occur
15de0 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 , pointers retur
15df0 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 ned by prior.**
15e00 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
15e10 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 _column_blob(),
15e20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
15e30 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a ext(), and/or.**
15e40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
15e50 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 text16() may be
15e60 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 0a 2a 2a invalidated. .**
15e70 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e Type conversion
15e80 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e s and pointer in
15e90 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 validations migh
15ea0 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 t occur.** in th
15eb0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 e following case
15ec0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
15ed0 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e <li><p> The in
15ee0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 itial content is
15ef0 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 a BLOB and sqli
15f00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
15f10 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f ) .** o
15f20 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
15f30 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c _text16() is cal
15f40 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 led. A zero-ter
15f50 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a minator might.**
15f60 20 20 20 20 20 20 20 20 20 20 6e 65 65 64 20 74 need t
15f70 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 o be added to th
15f80 65 20 73 74 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c e string.</p></l
15f90 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e i>.**.** <li><p>
15fa0 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f The initial co
15fb0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 ntent is UTF-8 t
15fc0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f ext and sqlite3_
15fd0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
15fe0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
15ff0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
16000 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 ext16() is calle
16010 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 d. The content
16020 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 must be converte
16030 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f d.** to
16040 20 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69 UTF-16.</p></li
16050 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 >.**.** <li><p>
16060 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e The initial con
16070 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 tent is UTF-16 t
16080 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f ext and sqlite3_
16090 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f column_bytes() o
160a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71 r.** sq
160b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
160c0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 t() is called.
160d0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 The content must
160e0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a be converted.**
160f0 20 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46 to UTF
16100 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20 -8.</p></li>.**
16110 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 </ul>.**.** Conv
16120 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 ersions between
16130 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 UTF-16be and UTF
16140 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 -16le are always
16150 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 done in place a
16160 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 nd do.** not inv
16170 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 alidate a prior
16180 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 pointer, though
16190 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f of course the co
161a0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 ntent of the buf
161b0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 fer.** that the
161c0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f prior pointer po
161d0 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 ints to will hav
161e0 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e e been modified.
161f0 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a Other kinds.**
16200 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 of conversion a
16210 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 re done in place
16220 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 when it is poss
16230 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 ible, but someti
16240 6d 65 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 me it is.** not
16250 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 possible and in
16260 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f those cases prio
16270 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 r pointers are i
16280 6e 76 61 6c 69 64 61 74 65 64 2e 20 20 0a 2a 2a nvalidated. .**
16290 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 .** The safest a
162a0 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 nd easiest to re
162b0 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 member policy is
162c0 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 to invoke these
162d0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 routines.** in
162e0 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
162f0 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a wing ways:.**.**
16300 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 <ul>.** <li>s
16310 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
16320 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 xt() followed by
16330 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
16340 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 bytes()</li>.**
16350 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c <li>sqlite3_col
16360 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f umn_blob() follo
16370 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 wed by sqlite3_c
16380 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c olumn_bytes()</l
16390 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 i>.** <li>sqlit
163a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
163b0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 () followed by s
163c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
163d0 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 tes16()</li>.**
163e0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 </ul>.**.** In
163f0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 other words, you
16400 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c should call sql
16410 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
16420 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 (), sqlite3_colu
16430 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72 mn_blob(),.** or
16440 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
16450 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 text16() first t
16460 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 o force the resu
16470 6c 74 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 lt into the desi
16480 72 65 64 0a 2a 2a 20 66 6f 72 6d 61 74 2c 20 74 red.** format, t
16490 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 hen invoke sqlit
164a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
164b0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c ) or sqlite3_col
164c0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f umn_bytes16() to
164d0 0a 2a 2a 20 66 69 6e 64 20 74 68 65 20 73 69 7a .** find the siz
164e0 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e e of the result.
164f0 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c Do not mix cal
16500 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c l to sqlite3_col
16510 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a umn_text() or.**
16520 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
16530 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c blob() with call
16540 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
16550 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2e 20 20 umn_bytes16().
16560 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69 And do not.** mi
16570 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 x calls to sqlit
16580 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
16590 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f () with calls to
165a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
165b0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 bytes()..**.** T
165c0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 he pointers retu
165d0 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 rned are valid u
165e0 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 ntil a type conv
165f0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 ersion occurs as
16600 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 .** described ab
16610 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 ove, or until [s
16620 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f qlite3_step()] o
16630 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
16640 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
16650 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 e3_finalize()] i
16660 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d s called. The m
16670 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 emory space used
16680 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 to hold strings
16690 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62 73 20 69 73 .** and blobs is
166a0 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 freed automatic
166b0 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 ally. Do <b>not
166c0 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f </b> pass the po
166d0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a inters returned.
166e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
166f0 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c mn_blob()], [sql
16700 69 74 65 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 ite_column_text(
16710 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 20 0a 2a )], etc. into .*
16720 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * [sqlite3_free(
16730 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d )]..**.** If a m
16740 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
16750 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 error occurs du
16760 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 ring the evaluat
16770 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 ion of any.** of
16780 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c these routines,
16790 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 a default value
167a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 is returned. T
167b0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 he default value
167c0 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 .** is either th
167d0 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 e integer 0, the
167e0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
167f0 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 number 0.0, or a
16800 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 NULL.** pointer
16810 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 . Subsequent ca
16820 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
16830 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 errcode()] will
16840 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 return.** [SQLIT
16850 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a 63 6f 6e E_NOMEM]..*/.con
16860 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
16870 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c _column_blob(sql
16880 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
16890 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 iCol);.int sqlit
168a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
168b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
168c0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 nt iCol);.int sq
168d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
168e0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d es16(sqlite3_stm
168f0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 t*, int iCol);.d
16900 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f ouble sqlite3_co
16910 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 lumn_double(sqli
16920 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
16930 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 Col);.int sqlite
16940 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 3_column_int(sql
16950 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
16960 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 iCol);.sqlite3_i
16970 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c nt64 sqlite3_col
16980 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 umn_int64(sqlite
16990 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
169a0 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e l);.const unsign
169b0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 ed char *sqlite3
169c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c _column_text(sql
169d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
169e0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 iCol);.const voi
169f0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
16a00 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 n_text16(sqlite3
16a10 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
16a20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
16a30 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 olumn_type(sqlit
16a40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
16a50 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c ol);.sqlite3_val
16a60 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ue *sqlite3_colu
16a70 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 mn_value(sqlite3
16a80 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
16a90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
16aa0 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 EF: Destroy A Pr
16ab0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
16ac0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 Object.**.** Th
16ad0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 e sqlite3_finali
16ae0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 ze() function is
16af0 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 called to delet
16b00 65 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 e a .** [sqlite3
16b10 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 _stmt | compiled
16b20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e SQL statement].
16b30 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e If the statemen
16b40 74 20 77 61 73 0a 2a 2a 20 65 78 65 63 75 74 65 t was.** execute
16b50 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 d successfully,
16b60 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 or not executed
16b70 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20 53 51 4c at all, then SQL
16b80 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e ITE_OK is return
16b90 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65 63 75 74 ed..** If execut
16ba0 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 ion of the state
16bb0 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e ment failed then
16bc0 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f an .** [SQLITE_
16bd0 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f ERROR | error co
16be0 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 de] or [SQLITE_I
16bf0 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 OERR_READ | exte
16c00 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d nded error code]
16c10 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e .** is returned.
16c20 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 .**.** This rou
16c30 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c tine can be call
16c40 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 ed at any point
16c50 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 during the execu
16c60 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b tion of the.** [
16c70 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 76 sqlite3_stmt | v
16c80 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 5d 2e irtual machine].
16c90 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61 6c If the virtual
16ca0 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 machine has not
16cb0 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 .** completed e
16cc0 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 xecution when th
16cd0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 is routine is ca
16ce0 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 lled, that is li
16cf0 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 ke.** encounteri
16d00 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 ng an error or a
16d10 6e 20 69 6e 74 65 72 72 75 70 74 2e 20 20 28 53 n interrupt. (S
16d20 65 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 ee [sqlite3_inte
16d30 72 72 75 70 74 28 29 5d 2e 29 20 0a 2a 2a 20 49 rrupt()].) .** I
16d40 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 ncomplete update
16d50 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 s may be rolled
16d60 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 back and transac
16d70 74 69 6f 6e 73 20 63 61 6e 63 65 6c 6c 65 64 2c tions cancelled,
16d80 20 20 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 .** depending
16d90 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 on the circumsta
16da0 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 20 0a 2a nces, and the .*
16db0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 * [SQLITE_ERROR
16dc0 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 72 | result code] r
16dd0 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 eturned will be
16de0 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a [SQLITE_ABORT]..
16df0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 */.int sqlite3_f
16e00 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f inalize(sqlite3_
16e10 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
16e20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
16e30 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 eset A Prepared
16e40 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
16e50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
16e60 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 e3_reset() funct
16e70 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f ion is called to
16e80 20 72 65 73 65 74 20 61 20 0a 2a 2a 20 5b 73 71 reset a .** [sq
16e90 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d lite3_stmt | com
16ea0 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d piled SQL statem
16eb0 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 ent] object..**
16ec0 62 61 63 6b 20 74 6f 20 69 74 27 73 20 69 6e 69 back to it's ini
16ed0 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 tial state, read
16ee0 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 y to be re-execu
16ef0 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 ted..** Any SQL
16f00 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 statement variab
16f10 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c les that had val
16f20 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 ues bound to the
16f30 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b m using.** the [
16f40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
16f50 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 b | sqlite3_bind
16f60 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e _*() API] retain
16f70 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a their values..*
16f80 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 * Use [sqlite3_c
16f90 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d lear_bindings()]
16fa0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 to reset the bi
16fb0 6e 64 69 6e 67 73 2e 0a 2a 2f 0a 69 6e 74 20 73 ndings..*/.int s
16fc0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c qlite3_reset(sql
16fd0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
16fe0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
16ff0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 EF: Create Or Re
17000 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 define SQL Funct
17010 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ions.**.** The f
17020 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e ollowing two fun
17030 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 ctions are used
17040 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 to add SQL funct
17050 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 ions or aggregat
17060 65 73 0a 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65 es.** or to rede
17070 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f fine the behavio
17080 72 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 r of existing SQ
17090 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 L functions or a
170a0 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 0a ggregates. The.
170b0 2a 2a 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e ** difference on
170c0 6c 79 20 62 65 74 77 65 65 6e 20 74 68 65 20 74 ly between the t
170d0 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73 wo is that the s
170e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c econd parameter,
170f0 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 the.** name of
17100 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e the (scalar) fun
17110 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 ction or aggrega
17120 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 te, is encoded i
17130 6e 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 n UTF-8 for.** s
17140 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
17150 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 nction() and UTF
17160 2d 31 36 20 66 6f 72 20 73 71 6c 69 74 65 33 5f -16 for sqlite3_
17170 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
17180 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6()..**.** The f
17190 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
171a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 20 7c 20 the [sqlite3 |
171b0 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 5d database handle]
171c0 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 0a that holds the.
171d0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ** SQL function
171e0 6f 72 20 61 67 67 72 65 67 61 74 65 20 69 73 20 or aggregate is
171f0 74 6f 20 62 65 20 61 64 64 65 64 20 6f 72 20 72 to be added or r
17200 65 64 65 66 69 6e 65 64 2e 20 49 66 20 61 20 73 edefined. If a s
17210 69 6e 67 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d ingle.** program
17220 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 uses more than
17230 6f 6e 65 20 64 61 74 61 62 61 73 65 20 68 61 6e one database han
17240 64 6c 65 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 dle internally,
17250 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 then SQL.** func
17260 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 tions or aggrega
17270 74 65 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 tes must be adde
17280 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 d individually t
17290 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 0a o each database.
172a0 2a 2a 20 68 61 6e 64 6c 65 20 77 69 74 68 20 77 ** handle with w
172b0 68 69 63 68 20 74 68 65 79 20 77 69 6c 6c 20 62 hich they will b
172c0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 e used..**.** Th
172d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
172e0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f er is the name o
172f0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 f the SQL functi
17300 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 on to be created
17310 0a 2a 2a 20 6f 72 20 72 65 64 65 66 69 6e 65 64 .** or redefined
17320 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e 67 74 68 20 ..** The length
17330 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c of the name is l
17340 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 imited to 255 by
17350 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f tes, exclusive o
17360 66 20 74 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74 f the .** zero-t
17370 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 erminator. Note
17380 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c that the name l
17390 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 ength limit is i
173a0 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 n bytes, not.**
173b0 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 characters. Any
173c0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 attempt to crea
173d0 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 te a function wi
173e0 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 th a longer name
173f0 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 .** will result
17400 69 6e 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 in an SQLITE_ERR
17410 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 OR error..**.**
17420 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
17430 74 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ter is the numbe
17440 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 r of arguments t
17450 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 hat the SQL func
17460 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
17470 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74 gate takes. If t
17480 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 his parameter is
17490 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
174a0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
174b0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
174c0 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 may take any nu
174d0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
174e0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 s..**.** The fou
174f0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 rth parameter, e
17500 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 TextRep, specifi
17510 65 73 20 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c es what .** [SQL
17520 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 ITE_UTF8 | text
17530 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 encoding] this S
17540 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 QL function pref
17550 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 ers for.** its p
17560 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 arameters. Any
17570 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 SQL function imp
17580 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 lementation shou
17590 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f ld be able to wo
175a0 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 rk.** work with
175b0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c UTF-8, UTF-16le,
175c0 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 or UTF-16be. B
175d0 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e ut some implemen
175e0 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a tations may be.*
175f0 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 * more efficient
17600 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 with one encodi
17610 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e ng than another.
17620 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 It is allowed
17630 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c to.** invoke sql
17640 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
17650 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 tion() or sqlite
17660 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
17670 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a n16() multiple.*
17680 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 * times with the
17690 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 same function b
176a0 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e ut with differen
176b0 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 t values of eTex
176c0 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 tRep..** When mu
176d0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 ltiple implement
176e0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
176f0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 me function are
17700 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 available, SQLit
17710 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 e.** will pick t
17720 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f he one that invo
17730 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 lves the least a
17740 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f mount of data co
17750 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 nversion..** If
17760 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 there is only a
17770 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 single implement
17780 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 ation which does
17790 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 0a 2a not care what.*
177a0 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 * text encoding
177b0 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 is used, then th
177c0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
177d0 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b t should be.** [
177e0 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a SQLITE_ANY]..**.
177f0 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72 ** The fifth par
17800 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 ameter is an arb
17810 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 itrary pointer.
17820 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 The implementat
17830 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75 ion.** of the fu
17840 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 nction can gain
17850 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 access to this p
17860 6f 69 6e 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20 ointer using.**
17870 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 [sqlite3_user_da
17880 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ta()]..**.** The
17890 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 seventh, eighth
178a0 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d and ninth param
178b0 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 eters, xFunc, xS
178c0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 tep and xFinal,
178d0 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 are.** pointers
178e0 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 to C-language fu
178f0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 nctions that imp
17900 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a lement the SQL.*
17910 2a 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 * function or ag
17920 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 gregate. A scala
17930 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 r SQL function r
17940 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 equires an imple
17950 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 mentation of.**
17960 74 68 65 20 78 46 75 6e 63 20 63 61 6c 6c 62 61 the xFunc callba
17970 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f ck only, NULL po
17980 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 inters should be
17990 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 passed as the x
179a0 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e Step.** and xFin
179b0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 al parameters. A
179c0 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 n aggregate SQL
179d0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 function require
179e0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 s an implementat
179f0 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20 ion.** of xStep
17a00 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e and xFinal and N
17a10 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 ULL should be pa
17a20 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 ssed for xFunc.
17a30 54 6f 20 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 To delete an.**
17a40 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e existing SQL fun
17a50 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 ction or aggrega
17a60 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f te, pass NULL fo
17a70 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 r all three func
17a80 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b tion.** callback
17a90 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 ..**.** It is pe
17aa0 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 rmitted to regis
17ab0 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 ter multiple imp
17ac0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
17ad0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 the same.** func
17ae0 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 tions with the s
17af0 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 ame name but wit
17b00 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 h either differi
17b10 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a ng numbers of.**
17b20 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 arguments or di
17b30 66 66 65 72 69 6e 67 20 70 65 72 66 65 72 72 65 ffering perferre
17b40 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 d text encodings
17b50 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 . SQLite will u
17b60 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d se.** the implem
17b70 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c entation most cl
17b80 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 osely matches th
17b90 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 e way in which t
17ba0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 he.** SQL functi
17bb0 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2f 0a 69 on is used..*/.i
17bc0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
17bd0 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 e_function(. sq
17be0 6c 69 74 65 33 20 2a 2c 0a 20 20 63 6f 6e 73 74 lite3 *,. const
17bf0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e char *zFunction
17c00 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 Name,. int nArg
17c10 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 ,. int eTextRep
17c20 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 ,. void*,. voi
17c30 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 d (*xFunc)(sqlit
17c40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
17c50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
17c60 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 ,. void (*xStep
17c70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
17c80 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
17c90 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
17ca0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 (*xFinal)(sqlite
17cb0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 3_context*).);.i
17cc0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
17cd0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 e_function16(.
17ce0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 sqlite3*,. cons
17cf0 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f t void *zFunctio
17d00 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
17d10 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
17d20 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f p,. void*,. vo
17d30 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 id (*xFunc)(sqli
17d40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
17d50 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
17d60 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 ),. void (*xSte
17d70 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 p)(sqlite3_conte
17d80 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
17d90 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
17da0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 (*xFinal)(sqlit
17db0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a e3_context*).);.
17dc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
17dd0 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a Text Encodings.
17de0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
17df0 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 tant define inte
17e00 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 ger codes that r
17e10 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 epresent the var
17e20 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 ious.** text enc
17e30 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 odings supported
17e40 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 by SQLite..*/.#
17e50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
17e60 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 F8 1.#
17e70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
17e80 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 F16LE 2.#
17e90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
17ea0 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 F16BE 3.#
17eb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
17ec0 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 F16 4
17ed0 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 /* Use native
17ee0 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 byte order */.#d
17ef0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 efine SQLITE_ANY
17f00 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 5
17f10 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 /* sqlite3_crea
17f20 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 te_function only
17f30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17f40 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 TE_UTF16_ALIGNED
17f50 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 8 /* sqlite
17f60 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
17f70 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a on only */../*.*
17f80 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 73 6f * CAPI3REF: Obso
17f90 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a lete Functions.*
17fa0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
17fb0 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77 ions are all now
17fc0 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f obsolete. In o
17fd0 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e rder to maintain
17fe0 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f .** backwards co
17ff0 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 mpatibility with
18000 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77 65 20 older code, we
18010 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75 70 70 continue to supp
18020 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e ort.** these fun
18030 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72 ctions. However
18040 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e , new developmen
18050 74 20 70 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c t projects shoul
18060 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 d avoid.** the u
18070 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 se of these func
18080 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 tions. To help
18090 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 encourage people
180a0 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 to avoid.** usi
180b0 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f ng these functio
180c0 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 ns, we are not g
180d0 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 oing to tell you
180e0 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a want they do..*
180f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 /.int sqlite3_ag
18100 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 gregate_count(sq
18110 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
18120 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 .int sqlite3_exp
18130 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d ired(sqlite3_stm
18140 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 t*);.int sqlite3
18150 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e _transfer_bindin
18160 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a gs(sqlite3_stmt*
18170 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 , sqlite3_stmt*)
18180 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c ;.int sqlite3_gl
18190 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 obal_recover(voi
181a0 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 d);.void sqlite3
181b0 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 _thread_cleanup(
181c0 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 void);../*.** CA
181d0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e PI3REF: Obtainin
181e0 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 g SQL Function P
181f0 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a arameter Values.
18200 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 **.** The C-lang
18210 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 uage implementat
18220 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 ion of SQL funct
18230 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
18240 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 tes uses.** this
18250 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 set of interfac
18260 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 e routines to ac
18270 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 cess the paramet
18280 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 er values on.**
18290 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 the function or
182a0 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a aggregate..**.**
182b0 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 The xFunc (for
182c0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 scalar functions
182d0 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 ) or xStep (for
182e0 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 aggregates) para
182f0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 meters.** to [sq
18300 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
18310 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 ction()] and [sq
18320 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
18330 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 ction16()].** de
18340 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 fine callbacks t
18350 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 hat implement th
18360 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 e SQL functions
18370 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a and aggregates..
18380 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d ** The 4th param
18390 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 eter to these ca
183a0 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 llbacks is an ar
183b0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
183c0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 to.** [sqlite3_v
183d0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 alue] objects.
183e0 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 There is one [sq
183f0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
18400 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 ect for.** each
18410 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
18420 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 SQL function.
18430 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
18440 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 re used to.** ex
18450 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f tract values fro
18460 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 m the [sqlite3_v
18470 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a alue] objects..*
18480 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
18490 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 nes work just li
184a0 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e ke the correspon
184b0 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 ding .** [sqlite
184c0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20 3_column_blob |
184d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a sqlite3_column_*
184e0 20 72 6f 75 74 69 6e 65 73 5d 20 65 78 63 65 70 routines] excep
184f0 74 20 74 68 61 74 20 0a 2a 2a 20 74 68 65 73 65 t that .** these
18500 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 routines take a
18510 20 73 69 6e 67 6c 65 20 5b 73 71 6c 69 74 65 33 single [sqlite3
18520 5f 76 61 6c 75 65 2a 5d 20 70 6f 69 6e 74 65 72 _value*] pointer
18530 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 instead.** of a
18540 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a n [sqlite3_stmt*
18550 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e ] pointer and an
18560 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 integer column
18570 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 number..**.** Th
18580 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
18590 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 text16() interfa
185a0 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 ce extracts a UT
185b0 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e F16 string.** in
185c0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
185d0 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f -order of the ho
185e0 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 st machine. The
185f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
18600 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 e_text16be() and
18610 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
18620 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 ext16le() interf
18630 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 aces.** extract
18640 55 54 46 31 36 20 73 74 72 69 6e 67 73 20 61 73 UTF16 strings as
18650 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 big-endian and
18660 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 little-endian re
18670 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a spectively..**.*
18680 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 * The sqlite3_va
18690 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 lue_numeric_type
186a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 () interface att
186b0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a empts to apply.*
186c0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 * numeric affini
186d0 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e ty to the value.
186e0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 This means tha
186f0 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a t an attempt is.
18700 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 ** made to conve
18710 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 rt the value to
18720 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c an integer or fl
18730 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 oating point. I
18740 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 f.** such a conv
18750 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 ersion is possib
18760 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 le without loss
18770 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 of information (
18780 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 77 6f 72 64 in order.** word
18790 73 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 s if the value i
187a0 73 20 6f 72 69 67 69 6e 61 6c 20 61 20 73 74 72 s original a str
187b0 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c ing that looks l
187c0 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a ike a number).**
187d0 20 74 68 65 6e 20 69 74 20 69 73 20 64 6f 6e 65 then it is done
187e0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 . Otherwise no
187f0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 conversion occur
18800 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c s. The .** [SQL
18810 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 ITE_INTEGER | da
18820 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f tatype] after co
18830 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 nversion is retu
18840 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 rned..**.** Plea
18850 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 se pay particula
18860 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 r attention to t
18870 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 he fact that the
18880 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a pointer that.**
18890 20 69 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f is returned fro
188a0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 m [sqlite3_value
188b0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 _blob()], [sqlit
188c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d e3_value_text()]
188d0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
188e0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d _value_text16()]
188f0 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 can be invalida
18900 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 ted by a subsequ
18910 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ent call to.** [
18920 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
18930 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 tes()], [sqlite3
18940 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 _value_bytes16()
18950 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
18960 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
18970 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
18980 74 65 78 74 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a text16()]. .**.
18990 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
189a0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 s must be called
189b0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 from the same t
189c0 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 hread as.** the
189d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 SQL function tha
189e0 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 73 t supplied the s
189f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20 70 61 qlite3_value* pa
18a00 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 20 4f 72 2c rameters..** Or,
18a10 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f if the sqlite3_
18a20 76 61 6c 75 65 2a 20 61 72 67 75 6d 65 6e 74 20 value* argument
18a30 63 6f 6d 65 73 20 66 72 6f 6d 20 74 68 65 20 5b comes from the [
18a40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
18a50 61 6c 75 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 alue()].** inter
18a60 66 61 63 65 2c 20 74 68 65 6e 20 74 68 65 73 65 face, then these
18a70 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 routines should
18a80 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
18a90 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 0a the same thread.
18aa0 2a 2a 20 74 68 61 74 20 72 61 6e 20 5b 73 71 6c ** that ran [sql
18ab0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
18ac0 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 e()]..*/.const v
18ad0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c oid *sqlite3_val
18ae0 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f ue_blob(sqlite3_
18af0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c value*);.int sql
18b00 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
18b10 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
18b20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 ;.int sqlite3_va
18b30 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 lue_bytes16(sqli
18b40 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 te3_value*);.dou
18b50 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ble sqlite3_valu
18b60 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 e_double(sqlite3
18b70 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
18b80 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 lite3_value_int(
18b90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
18ba0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
18bb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 qlite3_value_int
18bc0 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 64(sqlite3_value
18bd0 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e *);.const unsign
18be0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 ed char *sqlite3
18bf0 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 _value_text(sqli
18c00 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e te3_value*);.con
18c10 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
18c20 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 _value_text16(sq
18c30 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 lite3_value*);.c
18c40 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
18c50 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c e3_value_text16l
18c60 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
18c70 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
18c80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
18c90 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 t16be(sqlite3_va
18ca0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
18cb0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 e3_value_type(sq
18cc0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
18cd0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
18ce0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 _numeric_type(sq
18cf0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a lite3_value*);..
18d00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
18d10 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 Obtain Aggregate
18d20 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 Function Contex
18d30 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c t.**.** The impl
18d40 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 ementation of ag
18d50 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
18d60 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72 tions use this r
18d70 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 outine to alloca
18d80 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72 te.** a structur
18d90 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 e for storing th
18da0 65 69 72 20 73 74 61 74 65 2e 20 20 54 68 65 20 eir state. The
18db0 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 first time this
18dc0 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 63 61 routine.** is ca
18dd0 6c 6c 65 64 20 66 6f 72 20 61 20 70 61 72 74 69 lled for a parti
18de0 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c cular aggregate,
18df0 20 61 20 6e 65 77 20 73 74 72 75 63 74 75 72 65 a new structure
18e00 20 6f 66 20 73 69 7a 65 20 6e 42 79 74 65 73 0a of size nBytes.
18e10 2a 2a 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 2c ** is allocated,
18e20 20 7a 65 72 6f 65 64 2c 20 61 6e 64 20 72 65 74 zeroed, and ret
18e30 75 72 6e 65 64 2e 20 20 4f 6e 20 73 75 62 73 65 urned. On subse
18e40 71 75 65 6e 74 20 63 61 6c 6c 73 20 28 66 6f 72 quent calls (for
18e50 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 61 67 67 the.** same agg
18e60 72 65 67 61 74 65 20 69 6e 73 74 61 6e 63 65 29 regate instance)
18e70 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 the same buffer
18e80 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 is returned. T
18e90 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
18ea0 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 61 67 67 72 n.** of the aggr
18eb0 65 67 61 74 65 20 63 61 6e 20 75 73 65 20 74 68 egate can use th
18ec0 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65 e returned buffe
18ed0 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 r to accumulate
18ee0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 data..**.** The
18ef0 62 75 66 66 65 72 20 61 6c 6c 6f 63 61 74 65 64 buffer allocated
18f00 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 is freed automa
18f10 74 69 63 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 tically by SQLit
18f20 65 20 77 68 61 6e 20 74 68 65 20 61 67 67 72 65 e whan the aggre
18f30 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f gate.** query co
18f40 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 ncludes..**.** T
18f50 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
18f60 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 er should be a c
18f70 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b opy of the .** [
18f80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
18f90 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 | SQL function c
18fa0 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 ontext] that is
18fb0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 the first.** par
18fc0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 ameter to the ca
18fd0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 llback routine t
18fe0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 hat implements t
18ff0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 he aggregate.**
19000 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
19010 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 This routine mus
19020 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d t be called from
19030 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
19040 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 in which.** the
19050 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 aggregate SQL f
19060 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
19070 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c ng..*/.void *sql
19080 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
19090 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 ontext(sqlite3_c
190a0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 ontext*, int nBy
190b0 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tes);../*.** CAP
190c0 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 I3REF: User Data
190d0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a For Functions.*
190e0 2a 0a 2a 2a 20 54 68 65 20 70 55 73 65 72 44 61 *.** The pUserDa
190f0 74 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ta parameter to
19100 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
19110 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a ate_function()].
19120 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
19130 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
19140 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 6()] routines.**
19150 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 used to registe
19160 72 20 75 73 65 72 20 66 75 6e 63 74 69 6f 6e 73 r user functions
19170 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f is available to
19180 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e .** the implemen
19190 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 66 75 tation of the fu
191a0 6e 63 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 69 nction using thi
191b0 73 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 s call..**.** Th
191c0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 is routine must
191d0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
191e0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
191f0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 n which.** the S
19200 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 QL function is r
19210 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 unning..*/.void
19220 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 *sqlite3_user_da
19230 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ta(sqlite3_conte
19240 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 xt*);../*.** CAP
19250 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 I3REF: Function
19260 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a Auxiliary Data.*
19270 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 *.** The followi
19280 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 ng two functions
19290 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 may be used by
192a0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 scalar SQL funct
192b0 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 ions to.** assoc
192c0 69 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77 iate meta-data w
192d0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c ith argument val
192e0 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 ues. If the same
192f0 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 value is passed
19300 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 to.** multiple
19310 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 invocations of t
19320 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 he same SQL func
19330 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 tion during quer
19340 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 y execution, und
19350 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 er.** some circu
19360 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 mstances the ass
19370 6f 63 69 61 74 65 64 20 6d 65 74 61 2d 64 61 74 ociated meta-dat
19380 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 a may be preserv
19390 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 ed. This may.**
193a0 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 be used, for exa
193b0 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 mple, to add a r
193c0 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f egular-expressio
193d0 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 n matching scala
193e0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 r.** function. T
193f0 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 he compiled vers
19400 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c ion of the regul
19410 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 ar expression is
19420 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 stored as.** me
19430 74 61 2d 64 61 74 61 20 61 73 73 6f 63 69 61 74 ta-data associat
19440 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 ed with the SQL
19450 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 value passed as
19460 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 the regular expr
19470 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 ession.** patter
19480 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 n. The compiled
19490 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 regular express
194a0 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 ion can be reuse
194b0 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a d on multiple.**
194c0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 invocations of
194d0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
194e0 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 n so that the or
194f0 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 iginal pattern s
19500 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f tring.** does no
19510 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 t need to be rec
19520 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 ompiled on each
19530 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a invocation..**.*
19540 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 * The sqlite3_ge
19550 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 t_auxdata() inte
19560 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
19570 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d pointer to the m
19580 65 74 61 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f eta-data.** asso
19590 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
195a0 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c Nth argument val
195b0 75 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e ue to the curren
195c0 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a t SQL function.*
195d0 2a 20 63 61 6c 6c 2c 20 77 68 65 72 65 20 4e 20 * call, where N
195e0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 is the second pa
195f0 72 61 6d 65 74 65 72 2e 20 49 66 20 6e 6f 20 6d rameter. If no m
19600 65 74 61 2d 64 61 74 61 20 68 61 73 20 62 65 65 eta-data has bee
19610 6e 20 73 65 74 20 66 6f 72 0a 2a 2a 20 74 68 61 n set for.** tha
19620 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 20 t value, then a
19630 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 NULL pointer is
19640 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
19650 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f The sqlite3_set_
19660 61 75 78 64 61 74 61 28 29 20 69 73 20 75 73 65 auxdata() is use
19670 64 20 74 6f 20 61 73 73 6f 63 69 61 74 65 20 6d d to associate m
19680 65 74 61 2d 64 61 74 61 20 77 69 74 68 20 61 6e eta-data with an
19690 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e SQL.** function
196a0 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 74 argument. The t
196b0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 hird parameter i
196c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
196d0 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 he meta-data.**
196e0 74 6f 20 62 65 20 61 73 73 6f 63 69 61 74 65 64 to be associated
196f0 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 75 73 with the Nth us
19700 65 72 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 er function argu
19710 6d 65 6e 74 20 76 61 6c 75 65 2e 20 54 68 65 20 ment value. The
19720 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 fourth.** parame
19730 74 65 72 20 73 70 65 63 69 66 69 65 73 20 61 20 ter specifies a
19740 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 destructor that
19750 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 6f will be called o
19760 6e 20 74 68 65 20 6d 65 74 61 2d 0a 2a 2a 20 64 n the meta-.** d
19770 61 74 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 72 ata pointer to r
19780 65 6c 65 61 73 65 20 69 74 20 77 68 65 6e 20 69 elease it when i
19790 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 t is no longer r
197a0 65 71 75 69 72 65 64 2e 20 49 66 20 74 68 65 20 equired. If the
197b0 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20 69 .** destructor i
197c0 73 20 4e 55 4c 4c 2c 20 69 74 20 69 73 20 6e 6f s NULL, it is no
197d0 74 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a t invoked..**.**
197e0 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 In practice, me
197f0 74 61 2d 64 61 74 61 20 69 73 20 70 72 65 73 65 ta-data is prese
19800 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e rved between fun
19810 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a ction calls for.
19820 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 ** expressions t
19830 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 hat are constant
19840 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 at compile time
19850 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 . This includes
19860 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 literal.** value
19870 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 s and SQL variab
19880 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 les..**.** These
19890 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 routines must b
198a0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
198b0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
198c0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 which.** the SQ
198d0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 L function is ru
198e0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a nning..*/.void *
198f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
19900 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ata(sqlite3_cont
19910 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 ext*, int);.void
19920 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
19930 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e data(sqlite3_con
19940 74 65 78 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 text*, int, void
19950 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 *, void (*)(void
19960 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *));.../*.** CAP
19970 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 I3REF: Constants
19980 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 Defining Specia
19990 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 l Destructor Beh
199a0 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 avior.**.** Thes
199b0 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 e are special va
199c0 6c 75 65 20 66 6f 72 20 74 68 65 20 64 65 73 74 lue for the dest
199d0 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 ructor that is p
199e0 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a assed in as the.
199f0 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e ** final argumen
19a00 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 t to routines li
19a10 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 ke [sqlite3_resu
19a20 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 lt_blob()]. If
19a30 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a the destructor.*
19a40 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 * argument is SQ
19a50 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 LITE_STATIC, it
19a60 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 means that the c
19a70 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 ontent pointer i
19a80 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e s constant.** an
19a90 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 d will never cha
19aa0 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f nge. It does no
19ab0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 t need to be des
19ac0 74 72 6f 79 65 64 2e 20 20 54 68 65 20 0a 2a 2a troyed. The .**
19ad0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e SQLITE_TRANSIEN
19ae0 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 T value means th
19af0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 at the content w
19b00 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 ill likely chang
19b10 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 e in.** the near
19b20 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 future and that
19b30 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d SQLite should m
19b40 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 ake its own priv
19b50 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 ate copy of.** t
19b60 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 he content befor
19b70 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a e returning..**.
19b80 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 ** The typedef i
19b90 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 s necessary to w
19ba0 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c ork around probl
19bb0 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a ems in certain.*
19bc0 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e * C++ compilers.
19bd0 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 See ticket #21
19be0 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 91..*/.typedef v
19bf0 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 oid (*sqlite3_de
19c00 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 structor_type)(v
19c10 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 oid*);.#define S
19c20 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 QLITE_STATIC
19c30 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 ((sqlite3_dest
19c40 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 ructor_type)0).#
19c50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 define SQLITE_TR
19c60 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 ANSIENT ((sqli
19c70 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 te3_destructor_t
19c80 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 ype)-1)../*.** C
19c90 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 API3REF: Setting
19ca0 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 The Result Of A
19cb0 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a n SQL Function.*
19cc0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
19cd0 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 nes are used by
19ce0 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 the xFunc or xFi
19cf0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 nal callbacks th
19d00 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 at.** implement
19d10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
19d20 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 d aggregates. S
19d30 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 ee.** [sqlite3_c
19d40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
19d50 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
19d60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
19d70 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 ()].** for addit
19d80 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
19d90 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 n..**.** These f
19da0 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 unctions work ve
19db0 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 ry much like the
19dc0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 .** [sqlite3_bi
19dd0 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 nd_blob | sqlite
19de0 33 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 3_bind_*] family
19df0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 of functions us
19e00 65 64 0a 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61 ed.** to bind va
19e10 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 lues to host par
19e20 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 ameters in prepa
19e30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a red statements..
19e40 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 0a ** Refer to the.
19e50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
19e60 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f _blob | sqlite3_
19e70 62 69 6e 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 bind_* documenta
19e80 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 tion] for.** add
19e90 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
19ea0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ion..**.** The s
19eb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
19ec0 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ror() and sqlite
19ed0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
19ee0 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 () functions.**
19ef0 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d cause the implem
19f00 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 ented SQL functi
19f10 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 on to throw an e
19f20 78 63 65 70 74 69 6f 6e 2e 20 20 54 68 65 0a 2a xception. The.*
19f30 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 * parameter to s
19f40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
19f50 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ror() or sqlite3
19f60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
19f70 29 0a 2a 2a 20 69 73 20 74 68 65 20 74 65 78 74 ).** is the text
19f80 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 of an error mes
19f90 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 sage..**.** The
19fa0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
19fb0 6f 6f 62 69 67 28 29 20 63 61 75 73 65 20 74 68 oobig() cause th
19fc0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 e function imple
19fd0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 mentation.** to
19fe0 74 68 72 6f 77 20 61 6e 64 20 65 72 72 6f 72 20 throw and error
19ff0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 indicating that
1a000 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 a string or BLOB
1a010 20 69 73 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 is to long.** t
1a020 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a o represent..**.
1a030 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
1a040 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 s must be called
1a050 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 from within the
1a060 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a same thread as.
1a070 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 ** the SQL funct
1a080 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 ion associated w
1a090 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ith the [sqlite3
1a0a0 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 _context] pointe
1a0b0 72 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 r..*/.void sqlit
1a0c0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 e3_result_blob(s
1a0d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
1a0e0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
1a0f0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
1a100 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
1a110 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 _result_double(s
1a120 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
1a130 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 double);.void s
1a140 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
1a150 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ror(sqlite3_cont
1a160 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 ext*, const char
1a170 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
1a180 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
1a190 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e or16(sqlite3_con
1a1a0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
1a1b0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 d*, int);.void s
1a1c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
1a1d0 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 ror_toobig(sqlit
1a1e0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f e3_context*);.vo
1a1f0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
1a200 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f t_int(sqlite3_co
1a210 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f ntext*, int);.vo
1a220 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
1a230 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f t_int64(sqlite3_
1a240 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 context*, sqlite
1a250 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 3_int64);.void s
1a260 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 qlite3_result_nu
1a270 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ll(sqlite3_conte
1a280 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 xt*);.void sqlit
1a290 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 e3_result_text(s
1a2a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
1a2b0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e const char*, in
1a2c0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
1a2d0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
1a2e0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 _result_text16(s
1a2f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
1a300 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
1a310 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
1a320 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
1a330 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 _result_text16le
1a340 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
1a350 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
1a360 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 int,void(*)(void
1a370 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 *));.void sqlite
1a380 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 3_result_text16b
1a390 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e(sqlite3_contex
1a3a0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c t*, const void*,
1a3b0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 int,void(*)(voi
1a3c0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 d*));.void sqlit
1a3d0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
1a3e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
1a3f0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a , sqlite3_value*
1a400 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
1a410 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 result_zeroblob(
1a420 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
1a430 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a , int n);../*.**
1a440 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e CAPI3REF: Defin
1a450 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 e New Collating
1a460 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 Sequences.**.**
1a470 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
1a480 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 are used to add
1a490 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 new collation se
1a4a0 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a quences to the.*
1a4b0 2a 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e * [sqlite3*] han
1a4c0 64 6c 65 20 73 70 65 63 69 66 69 65 64 20 61 73 dle specified as
1a4d0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
1a4e0 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ent. .**.** The
1a4f0 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 name of the new
1a500 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
1a510 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20 ce is specified
1a520 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e as a UTF-8 strin
1a530 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 g.** for sqlite3
1a540 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
1a550 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
1a560 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
1a570 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 _v2().** and a U
1a580 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 TF-16 string for
1a590 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
1a5a0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 20 collation16().
1a5b0 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 In all cases.**
1a5c0 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 the name is pass
1a5d0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
1a5e0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
1a5f0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 nt..**.** The th
1a600 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 ird argument mus
1a610 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 t be one of the
1a620 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 constants [SQLIT
1a630 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c E_UTF8],.** [SQL
1a640 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 ITE_UTF16LE] or
1a650 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d [SQLITE_UTF16BE]
1a660 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 , indicating tha
1a670 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c t the user-suppl
1a680 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 ied.** routine e
1a690 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 xpects to be pas
1a6a0 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 sed pointers to
1a6b0 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 strings encoded
1a6c0 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 using UTF-8,.**
1a6d0 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e UTF-16 little-en
1a6e0 64 69 61 6e 20 6f 72 20 55 54 46 2d 31 36 20 62 dian or UTF-16 b
1a6f0 69 67 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 ig-endian respec
1a700 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 tively..**.** A
1a710 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 pointer to the u
1a720 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 ser supplied rou
1a730 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 tine must be pas
1a740 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68 sed as the fifth
1a750 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 .** argument. If
1a760 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 it is NULL, thi
1a770 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 s is the same as
1a780 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f deleting the co
1a790 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 llation.** seque
1a7a0 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c nce (so that SQL
1a7b0 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 ite cannot call
1a7c0 69 74 20 61 6e 79 6d 6f 72 65 29 2e 20 45 61 63 it anymore). Eac
1a7d0 68 20 74 69 6d 65 20 74 68 65 20 75 73 65 72 0a h time the user.
1a7e0 2a 2a 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 ** supplied func
1a7f0 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c tion is invoked,
1a800 20 69 74 20 69 73 20 70 61 73 73 65 64 20 61 20 it is passed a
1a810 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 copy of the void
1a820 2a 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 * passed as.** t
1a830 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
1a840 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 nt to sqlite3_cr
1a850 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 eate_collation()
1a860 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 or.** sqlite3_c
1a870 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 reate_collation1
1a880 36 28 29 20 61 73 20 69 74 73 20 66 69 72 73 74 6() as its first
1a890 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
1a8a0 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 * The remaining
1a8b0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 arguments to the
1a8c0 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 20 72 user-supplied r
1a8d0 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 outine are two s
1a8e0 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 trings,.** each
1a8f0 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 represented by a
1a900 20 5b 6c 65 6e 67 74 68 2c 20 64 61 74 61 5d 20 [length, data]
1a910 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 pair and encoded
1a920 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 in the encoding
1a930 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 .** that was pas
1a940 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 sed as the third
1a950 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 argument when t
1a960 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 he collation seq
1a970 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 uence was.** reg
1a980 69 73 74 65 72 65 64 2e 20 54 68 65 20 75 73 65 istered. The use
1a990 72 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 r routine should
1a9a0 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 return negative
1a9b0 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 , zero or positi
1a9c0 76 65 20 69 66 0a 2a 2a 20 74 68 65 20 66 69 72 ve if.** the fir
1a9d0 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 st string is les
1a9e0 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f s than, equal to
1a9f0 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 , or greater tha
1aa00 6e 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 n the second.**
1aa10 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 string. i.e. (ST
1aa20 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 RING1 - STRING2)
1aa30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
1aa40 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
1aa50 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 tion_v2() works
1aa60 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 like sqlite3_cre
1aa70 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a ate_collation().
1aa80 2a 2a 20 65 78 63 61 70 74 20 74 68 61 74 20 69 ** excapt that i
1aa90 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 t takes an extra
1aaa0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
1aab0 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 is a destructor
1aac0 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 for.** the colla
1aad0 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 tion. The destr
1aae0 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 uctor is called
1aaf0 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 when the collati
1ab00 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 on is.** destroy
1ab10 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 ed and is passed
1ab20 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 a copy of the f
1ab30 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
1ab40 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a void* pointer.**
1ab50 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
1ab60 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
1ab70 5f 76 32 28 29 2e 20 20 43 6f 6c 6c 61 74 69 6f _v2(). Collatio
1ab80 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 ns are destroyed
1ab90 20 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72 when.** they ar
1aba0 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 e overridden by
1abb0 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 later calls to t
1abc0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 he collation cre
1abd0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a ation functions.
1abe0 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b ** or when the [
1abf0 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61 sqlite3*] databa
1ac00 73 65 20 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f se handle is clo
1ac10 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 sed using [sqlit
1ac20 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a e3_close()]..**.
1ac30 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
1ac40 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
1ac50 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 v2() interface i
1ac60 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 s experimental a
1ac70 6e 64 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f nd.** subject to
1ac80 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 change in futur
1ac90 65 20 72 65 6c 65 61 73 65 73 2e 20 20 54 68 65 e releases. The
1aca0 20 6f 74 68 65 72 20 63 6f 6c 6c 61 74 69 6f 6e other collation
1acb0 20 63 72 65 61 74 69 6f 6e 0a 2a 2a 20 66 75 6e creation.** fun
1acc0 63 74 69 6f 6e 73 20 61 72 65 20 73 74 61 62 6c ctions are stabl
1acd0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 e..*/.int sqlite
1ace0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
1acf0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 on(. sqlite3*,
1ad00 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
1ad10 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 Name, . int eTe
1ad20 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c xtRep, . void*,
1ad30 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 . int(*xCompare
1ad40 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
1ad50 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 t void*,int,cons
1ad60 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 t void*).);.int
1ad70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
1ad80 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 ollation_v2(. s
1ad90 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 qlite3*, . cons
1ada0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a t char *zName, .
1adb0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 int eTextRep,
1adc0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 . void*,. int(
1add0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a *xCompare)(void*
1ade0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
1adf0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
1ae00 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 ),. void(*xDest
1ae10 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 roy)(void*).);.i
1ae20 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
1ae30 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 e_collation16(.
1ae40 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f sqlite3*, . co
1ae50 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
1ae60 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 . int eTextRep
1ae70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e , . void*,. in
1ae80 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 t(*xCompare)(voi
1ae90 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
1aea0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
1aeb0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 d*).);../*.** CA
1aec0 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f PI3REF: Collatio
1aed0 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 n Needed Callbac
1aee0 6b 73 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 ks.**.** To avoi
1aef0 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 d having to regi
1af00 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 ster all collati
1af10 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 on sequences bef
1af20 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a ore a database.*
1af30 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 * can be used, a
1af40 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b single callback
1af50 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 function may be
1af60 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 registered with
1af70 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
1af80 20 68 61 6e 64 6c 65 20 74 6f 20 62 65 20 63 61 handle to be ca
1af90 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e lled whenever an
1afa0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 undefined colla
1afb0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 tion sequence is
1afc0 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a .** required..**
1afd0 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 .** If the funct
1afe0 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 ion is registere
1aff0 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 d using the sqli
1b000 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
1b010 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 eded() API,.** t
1b020 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 hen it is passed
1b030 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e the names of un
1b040 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f defined collatio
1b050 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 n sequences as s
1b060 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 trings.** encode
1b070 64 20 69 6e 20 55 54 46 2d 38 2e 20 49 66 20 73 d in UTF-8. If s
1b080 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
1b090 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 _needed16() is u
1b0a0 73 65 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a 2a sed, the names.*
1b0b0 2a 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 * are passed as
1b0c0 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e UTF-16 in machin
1b0d0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
1b0e0 64 65 72 2e 20 41 20 63 61 6c 6c 20 74 6f 20 65 der. A call to e
1b0f0 69 74 68 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f ither.** functio
1b100 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 n replaces any e
1b110 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b xisting callback
1b120 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
1b130 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
1b140 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 oked, the first
1b150 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 argument passed
1b160 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 is a copy.** of
1b170 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
1b180 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 ent to sqlite3_c
1b190 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 ollation_needed(
1b1a0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
1b1b0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
1b1c0 31 36 28 29 2e 20 54 68 65 20 73 65 63 6f 6e 64 16(). The second
1b1d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
1b1e0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e database.** han
1b1f0 64 6c 65 2e 20 54 68 65 20 74 68 69 72 64 20 61 dle. The third a
1b200 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f rgument is one o
1b210 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c f [SQLITE_UTF8],
1b220 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 [SQLITE_UTF16BE
1b230 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 ], or.** [SQLITE
1b240 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 _UTF16LE], indic
1b250 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 ating the most d
1b260 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 esirable form of
1b270 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a the collation.*
1b280 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 * sequence funct
1b290 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 54 68 ion required. Th
1b2a0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
1b2b0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f er is the name o
1b2c0 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 f the.** require
1b2d0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 d collation sequ
1b2e0 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ence..**.** The
1b2f0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
1b300 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 n should registe
1b310 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f r the desired co
1b320 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a llation using.**
1b330 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
1b340 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b _collation()], [
1b350 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
1b360 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f ollation16()], o
1b370 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 r.** [sqlite3_cr
1b380 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
1b390 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 2()]..*/.int sql
1b3a0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
1b3b0 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 eeded(. sqlite3
1b3c0 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 *, . void*, .
1b3d0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
1b3e0 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 lite3*,int eText
1b3f0 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 Rep,const char*)
1b400 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
1b410 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
1b420 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 16(. sqlite3*,
1b430 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 . void*,. void
1b440 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
1b450 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 3*,int eTextRep,
1b460 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a const void*).);.
1b470 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 ./*.** Specify t
1b480 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e he key for an en
1b490 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 crypted database
1b4a0 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 . This routine
1b4b0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c should be.** cal
1b4c0 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 led right after
1b4d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a sqlite3_open()..
1b4e0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 **.** The code t
1b4f0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 o implement this
1b500 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 API is not avai
1b510 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 lable in the pub
1b520 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f lic release.** o
1b530 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 f SQLite..*/.int
1b540 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 sqlite3_key(.
1b550 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
1b560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
1b570 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 * Database to be
1b580 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f rekeyed */. co
1b590 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 nst void *pKey,
1b5a0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 int nKey /*
1b5b0 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f The key */.);../
1b5c0 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 *.** Change the
1b5d0 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 key on an open d
1b5e0 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 atabase. If the
1b5f0 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 current databas
1b600 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 e is not.** encr
1b610 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 ypted, this rout
1b620 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 ine will encrypt
1b630 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 it. If pNew==0
1b640 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 or nNew==0, the
1b650 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 .** database is
1b660 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a decrypted..**.**
1b670 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 The code to imp
1b680 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 lement this API
1b690 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 is not available
1b6a0 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 in the public r
1b6b0 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c elease.** of SQL
1b6c0 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ite..*/.int sqli
1b6d0 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c te3_rekey(. sql
1b6e0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
1b6f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
1b700 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 atabase to be re
1b710 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 keyed */. const
1b720 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 void *pKey, int
1b730 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 nKey /* The
1b740 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a new key */.);..
1b750 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1b760 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 Suspend Executi
1b770 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 on For A Short T
1b780 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 ime.**.** This f
1b790 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 unction causes t
1b7a0 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 he current threa
1b7b0 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 d to suspend exe
1b7c0 63 75 74 69 6f 6e 0a 2a 2a 20 61 20 6e 75 6d 62 cution.** a numb
1b7d0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e er of millisecon
1b7e0 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 ds specified in
1b7f0 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a its parameter..*
1b800 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 *.** If the oper
1b810 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 ating system doe
1b820 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c s not support sl
1b830 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 eep requests wit
1b840 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e h .** millisecon
1b850 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f d time resolutio
1b860 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 n, then the time
1b870 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 will be rounded
1b880 20 75 70 20 74 6f 20 0a 2a 2a 20 74 68 65 20 6e up to .** the n
1b890 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 earest second. T
1b8a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c he number of mil
1b8b0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 liseconds of sle
1b8c0 65 70 20 61 63 74 75 61 6c 6c 79 20 0a 2a 2a 20 ep actually .**
1b8d0 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 requested from t
1b8e0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
1b8f0 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e tem is returned.
1b900 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d .**.** SQLite im
1b910 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e plements this in
1b920 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 terface by calli
1b930 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a ng the xSleep().
1b940 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 ** method of the
1b950 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 default [sqlite
1b960 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 3_vfs] object..*
1b970 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c /.int sqlite3_sl
1b980 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a eep(int);../*.**
1b990 20 43 41 50 49 33 52 45 46 3a 20 20 4e 61 6d 65 CAPI3REF: Name
1b9a0 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 Of The Folder H
1b9b0 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 olding Temporary
1b9c0 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 49 66 20 Files.**.** If
1b9d0 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 this global vari
1b9e0 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 able is made to
1b9f0 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e point to a strin
1ba00 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 g which is.** th
1ba10 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 e name of a fold
1ba20 65 72 20 28 61 2e 6b 61 2e 20 64 69 72 65 63 74 er (a.ka. direct
1ba30 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 ory), then all t
1ba40 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a emporary files.*
1ba50 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c * created by SQL
1ba60 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 ite will be plac
1ba70 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 ed in that direc
1ba80 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 tory. If this v
1ba90 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55 ariable.** is NU
1baa0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e LL pointer, then
1bab0 20 53 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73 SQLite does a s
1bac0 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 earch for an app
1bad0 72 6f 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61 ropriate tempora
1bae0 72 79 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63 ry.** file direc
1baf0 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 63 65 tory..**.** Once
1bb00 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
1bb10 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 ] has been calle
1bb20 64 2c 20 63 68 61 6e 67 69 6e 67 20 74 68 69 73 d, changing this
1bb30 20 76 61 72 69 61 62 6c 65 20 77 69 6c 6c 0a 2a variable will.*
1bb40 2a 20 69 6e 76 61 6c 69 64 61 74 65 20 74 68 65 * invalidate the
1bb50 20 63 75 72 72 65 6e 74 20 74 65 6d 70 6f 72 61 current tempora
1bb60 72 79 20 64 61 74 61 62 61 73 65 2c 20 69 66 20 ry database, if
1bb70 61 6e 79 2e 20 20 47 65 6e 65 72 61 6c 6c 79 20 any. Generally
1bb80 73 70 65 61 6b 69 6e 67 2c 0a 2a 2a 20 69 74 20 speaking,.** it
1bb90 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 69 is not safe to i
1bba0 6e 76 6f 6b 65 20 74 68 69 73 20 72 6f 75 74 69 nvoke this routi
1bbb0 6e 65 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 ne after [sqlite
1bbc0 33 5f 6f 70 65 6e 28 29 5d 20 68 61 73 0a 2a 2a 3_open()] has.**
1bbd0 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2f been called..*/
1bbe0 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 .SQLITE_EXTERN c
1bbf0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d har *sqlite3_tem
1bc00 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a p_directory;../*
1bc10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 54 .** CAPI3REF: T
1bc20 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 est To See If Th
1bc30 65 20 44 61 74 61 62 73 65 20 49 73 20 49 6e 20 e Databse Is In
1bc40 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 Auto-Commit Mode
1bc50 0a 2a 2a 0a 2a 2a 20 54 65 73 74 20 74 6f 20 73 .**.** Test to s
1bc60 65 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f ee whether or no
1bc70 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 t the database c
1bc80 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 onnection is in
1bc90 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 6d 6f autocommit.** mo
1bca0 64 65 2e 20 20 52 65 74 75 72 6e 20 54 52 55 45 de. Return TRUE
1bcb0 20 69 66 20 69 74 20 69 73 20 61 6e 64 20 46 41 if it is and FA
1bcc0 4c 53 45 20 69 66 20 6e 6f 74 2e 20 20 41 75 74 LSE if not. Aut
1bcd0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 ocommit mode is
1bce0 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 on.** by default
1bcf0 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 69 73 . Autocommit is
1bd00 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 42 disabled by a B
1bd10 45 47 49 4e 20 73 74 61 74 65 6d 65 6e 74 20 61 EGIN statement a
1bd20 6e 64 20 72 65 65 6e 61 62 6c 65 64 0a 2a 2a 20 nd reenabled.**
1bd30 62 79 20 74 68 65 20 6e 65 78 74 20 43 4f 4d 4d by the next COMM
1bd40 49 54 20 6f 72 20 52 4f 4c 4c 42 41 43 4b 2e 0a IT or ROLLBACK..
1bd50 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 **.** If another
1bd60 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 thread changes
1bd70 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 the autocommit s
1bd80 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 tatus of the dat
1bd90 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
1bda0 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 ion while this r
1bdb0 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e outine is runnin
1bdc0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 g, then the retu
1bdd0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 rn value.** is u
1bde0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 ndefined..*/.int
1bdf0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 sqlite3_get_aut
1be00 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a ocommit(sqlite3*
1be10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1be20 45 46 3a 20 20 46 69 6e 64 20 54 68 65 20 44 61 EF: Find The Da
1be30 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 41 73 tabase Handle As
1be40 73 6f 63 69 61 74 65 64 20 57 69 74 68 20 41 20 sociated With A
1be50 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
1be60 6e 74 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 nt.**.** Return
1be70 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 the [sqlite3*] d
1be80 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 atabase handle t
1be90 6f 20 77 68 69 63 68 20 61 0a 2a 2a 20 5b 73 71 o which a.** [sq
1bea0 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 lite3_stmt | pre
1beb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1bec0 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20 54 68 69 belongs..** Thi
1bed0 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 64 61 s is the same da
1bee0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68 tabase handle th
1bef0 61 74 20 77 61 73 0a 2a 2a 20 74 68 65 20 66 69 at was.** the fi
1bf00 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
1bf10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 the [sqlite3_pre
1bf20 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 pare_v2()] or it
1bf30 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74 68 s variants.** th
1bf40 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 20 63 at was used to c
1bf50 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d reate the statem
1bf60 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 ent in the first
1bf70 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 place..*/.sqlit
1bf80 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 e3 *sqlite3_db_h
1bf90 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 andle(sqlite3_st
1bfa0 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 mt*);.../*.** CA
1bfb0 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 PI3REF: Commit A
1bfc0 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 nd Rollback Noti
1bfd0 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 fication Callbac
1bfe0 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 ks.**.** These r
1bff0 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 67 69 73 outines.** regis
1c000 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e ter callback fun
1c010 63 74 69 6f 6e 73 20 74 6f 20 62 65 20 69 6e 76 ctions to be inv
1c020 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 oked whenever a
1c030 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 69 transaction.** i
1c040 73 20 63 6f 6d 6d 69 74 74 65 64 20 6f 72 20 72 s committed or r
1c050 6f 6c 6c 65 64 20 62 61 63 6b 2e 20 20 54 68 65 olled back. The
1c060 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 pArg argument i
1c070 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 s passed through
1c080 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 .** to the callb
1c090 61 63 6b 2e 20 20 49 66 20 74 68 65 20 63 61 6c ack. If the cal
1c0a0 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 lback on a commi
1c0b0 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 t hook function
1c0c0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d .** returns non-
1c0d0 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 63 zero, then the c
1c0e0 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 ommit is convert
1c0f0 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 ed into a rollba
1c100 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f ck..**.** If ano
1c110 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 ther function wa
1c120 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 s previously reg
1c130 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 istered, its pAr
1c140 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 g value is retur
1c150 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 ned..** Otherwis
1c160 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e e NULL is return
1c170 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 ed..**.** Regist
1c180 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e ering a NULL fun
1c190 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 ction disables t
1c1a0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a he callback..**.
1c1b0 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f ** For the purpo
1c1c0 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c ses of this API,
1c1d0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
1c1e0 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 s said to have b
1c1f0 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 een .** rolled b
1c200 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 ack if an explic
1c210 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 it "ROLLBACK" st
1c220 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 atement is execu
1c230 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 ted, or.** an er
1c240 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e ror or constrain
1c250 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c t causes an impl
1c260 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f icit rollback to
1c270 20 6f 63 63 75 72 2e 20 54 68 65 20 0a 2a 2a 20 occur. The .**
1c280 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 callback is not
1c290 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 invoked if a tra
1c2a0 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f nsaction is auto
1c2b0 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 matically rolled
1c2c0 0a 2a 2a 20 62 61 63 6b 20 62 65 63 61 75 73 65 .** back because
1c2d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
1c2e0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 nnection is clos
1c2f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ed..**.** These
1c300 61 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c are experimental
1c310 20 69 6e 74 65 72 66 61 63 65 73 20 61 6e 64 20 interfaces and
1c320 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 are subject to c
1c330 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a hange..*/.void *
1c340 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 sqlite3_commit_h
1c350 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e ook(sqlite3*, in
1c360 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 t(*)(void*), voi
1c370 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 d*);.void *sqlit
1c380 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b e3_rollback_hook
1c390 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 (sqlite3*, void(
1c3a0 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 *)(void *), void
1c3b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1c3c0 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 REF: Data Change
1c3d0 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 Notification Ca
1c3e0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 52 65 llbacks.**.** Re
1c3f0 67 69 73 74 65 72 20 61 20 63 61 6c 6c 62 61 63 gister a callbac
1c400 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 k function with
1c410 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
1c420 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74 69 66 69 nection identifi
1c430 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 ed by the .** fi
1c440 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
1c450 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
1c460 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 ver a row is upd
1c470 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f ated, inserted o
1c480 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e r deleted..** An
1c490 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 y callback set b
1c4a0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c y a previous cal
1c4b0 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 l to this functi
1c4c0 6f 6e 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 on for the same
1c4d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
1c4e0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 nection is overr
1c4f0 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 idden..**.** The
1c500 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
1c510 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
1c520 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f the function to
1c530 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 20 0a invoke when a .
1c540 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 ** row is update
1c550 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 d, inserted or d
1c560 65 6c 65 74 65 64 2e 20 54 68 65 20 66 69 72 73 eleted. The firs
1c570 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
1c580 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a e callback is.**
1c590 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 a copy of the t
1c5a0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f hird argument to
1c5b0 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f sqlite3_update_
1c5c0 68 6f 6f 6b 28 29 2e 20 54 68 65 20 73 65 63 6f hook(). The seco
1c5d0 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 nd callback .**
1c5e0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 argument is one
1c5f0 6f 66 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 of SQLITE_INSERT
1c600 2c 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 , SQLITE_DELETE
1c610 6f 72 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 or SQLITE_UPDATE
1c620 2c 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f , depending.** o
1c630 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 n the operation
1c640 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 that caused the
1c650 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 callback to be i
1c660 6e 76 6f 6b 65 64 2e 20 54 68 65 20 74 68 69 72 nvoked. The thir
1c670 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72 74 68 d and .** fourth
1c680 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
1c690 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 e callback conta
1c6a0 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 in pointers to t
1c6b0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 he database and
1c6c0 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 .** table name c
1c6d0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 ontaining the af
1c6e0 66 65 63 74 65 64 20 72 6f 77 2e 20 54 68 65 20 fected row. The
1c6f0 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 final callback p
1c700 61 72 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a 20 arameter is .**
1c710 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 the rowid of the
1c720 20 72 6f 77 2e 20 49 6e 20 74 68 65 20 63 61 73 row. In the cas
1c730 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 e of an update,
1c740 74 68 69 73 20 69 73 20 74 68 65 20 72 6f 77 69 this is the rowi
1c750 64 20 61 66 74 65 72 20 0a 2a 2a 20 74 68 65 20 d after .** the
1c760 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 update takes pla
1c770 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 ce..**.** The up
1c780 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 date hook is not
1c790 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e invoked when in
1c7a0 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 ternal system ta
1c7b0 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 bles are.** modi
1c7c0 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 fied (i.e. sqlit
1c7d0 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c e_master and sql
1c7e0 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a ite_sequence)..*
1c7f0 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 *.** If another
1c800 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 function was pre
1c810 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 viously register
1c820 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c ed, its pArg val
1c830 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a ue is returned..
1c840 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c ** Otherwise NUL
1c850 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a L is returned..*
1c860 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f /.void *sqlite3_
1c870 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 update_hook(. s
1c880 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 qlite3*, . void
1c890 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c (*)(void *,int ,
1c8a0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 char const *,cha
1c8b0 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 r const *,sqlite
1c8c0 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 3_int64),. void
1c8d0 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 *.);../*.** CAPI
1c8e0 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 3REF: Enable Or
1c8f0 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 Disable Shared
1c900 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 0a 2a Pager Cache.**.*
1c910 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 * This routine e
1c920 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c nables or disabl
1c930 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f es the sharing o
1c940 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 f the database c
1c950 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 ache.** and sche
1c960 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 ma data structur
1c970 65 73 20 62 65 74 77 65 65 6e 20 63 6f 6e 6e 65 es between conne
1c980 63 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 73 61 ctions to the sa
1c990 6d 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 20 me database..**
1c9a0 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c Sharing is enabl
1c9b0 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 ed if the argume
1c9c0 6e 74 20 69 73 20 74 72 75 65 20 61 6e 64 20 64 nt is true and d
1c9d0 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 isabled if the a
1c9e0 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 66 61 rgument.** is fa
1c9f0 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e lse..**.** Begin
1ca00 6e 69 6e 67 20 69 6e 20 53 51 4c 69 74 65 20 76 ning in SQLite v
1ca10 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 63 61 ersion 3.5.0, ca
1ca20 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 che sharing is e
1ca30 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 nabled and disab
1ca40 6c 65 64 0a 2a 2a 20 66 6f 72 20 61 6e 20 65 6e led.** for an en
1ca50 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20 20 49 tire process. I
1ca60 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 n prior versions
1ca70 20 6f 66 20 53 51 4c 69 74 65 2c 20 73 68 61 72 of SQLite, shar
1ca80 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c ing was.** enabl
1ca90 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 ed or disabled f
1caa0 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73 or each thread s
1cab0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a eparately..**.**
1cac0 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69 The cache shari
1cad0 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 ng mode set by t
1cae0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 his interface ef
1caf0 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 fects all subseq
1cb00 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f uent.** calls to
1cb10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
1cb20 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
1cb30 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c _v2()], and [sql
1cb40 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a ite3_open16()]..
1cb50 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 ** Existing data
1cb60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
1cb70 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 continue use th
1cb80 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 74 e sharing mode t
1cb90 68 61 74 20 77 61 73 0a 2a 2a 20 69 6e 20 65 66 hat was.** in ef
1cba0 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 fect at the time
1cbb0 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 they were opene
1cbc0 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c d..**.** Virtual
1cbd0 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 tables cannot b
1cbe0 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73 68 e used with a sh
1cbf0 61 72 65 64 20 63 61 63 68 65 2e 20 20 57 68 65 ared cache. Whe
1cc00 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 n shared.** cach
1cc10 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 e is enabled, th
1cc20 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 e sqlite3_create
1cc30 5f 6d 6f 64 75 6c 65 28 29 20 41 50 49 20 75 73 _module() API us
1cc40 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a ed to register.*
1cc50 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 * virtual tables
1cc60 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 will always ret
1cc70 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a urn an error..**
1cc80 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
1cc90 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
1cca0 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 _OK] if shared c
1ccb0 61 63 68 65 20 77 61 73 0a 2a 2a 20 65 6e 61 62 ache was.** enab
1ccc0 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 led or disabled
1ccd0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 successfully. A
1cce0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 n [SQLITE_ERROR
1ccf0 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a | error code].**
1cd00 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 is returned oth
1cd10 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 erwise..**.** Sh
1cd20 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 ared cache is di
1cd30 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
1cd40 74 20 66 6f 72 20 62 61 63 6b 77 61 72 64 20 63 t for backward c
1cd50 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f ompatibility..*/
1cd60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 .int sqlite3_ena
1cd70 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 ble_shared_cache
1cd80 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 (int);../*.** CA
1cd90 50 49 33 52 45 46 3a 20 20 41 74 74 65 6d 70 74 PI3REF: Attempt
1cda0 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 To Free Heap Me
1cdb0 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d mory.**.** Attem
1cdc0 70 74 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 pt to free N byt
1cdd0 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 es of heap memor
1cde0 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e y by deallocatin
1cdf0 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a g non-essential.
1ce00 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
1ce10 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68 tions held by th
1ce20 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 e database libra
1ce30 72 79 20 28 65 78 61 6d 70 6c 65 3a 20 6d 65 6d ry (example: mem
1ce40 6f 72 79 20 0a 2a 2a 20 75 73 65 64 20 74 6f 20 ory .** used to
1ce50 63 61 63 68 65 20 64 61 74 61 62 61 73 65 20 70 cache database p
1ce60 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 ages to improve
1ce70 70 65 72 66 6f 72 6d 61 6e 63 65 29 2e 0a 2a 2a performance)..**
1ce80 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
1ce90 6e 20 69 73 20 6e 6f 74 20 61 20 70 61 72 74 20 n is not a part
1cea0 6f 66 20 73 74 61 6e 64 61 72 64 20 62 75 69 6c of standard buil
1ceb0 64 73 2e 20 20 49 74 20 69 73 20 6f 6e 6c 79 20 ds. It is only
1cec0 63 72 65 61 74 65 64 0a 2a 2a 20 69 66 20 53 51 created.** if SQ
1ced0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
1cee0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 with the SQLITE
1cef0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d _ENABLE_MEMORY_M
1cf00 41 4e 41 47 45 4d 45 4e 54 20 6d 61 63 72 6f 2e ANAGEMENT macro.
1cf10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
1cf20 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 release_memory(i
1cf30 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
1cf40 33 52 45 46 3a 20 20 49 6d 70 6f 73 65 20 41 20 3REF: Impose A
1cf50 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 Limit On Heap Si
1cf60 7a 65 0a 2a 2a 0a 2a 2a 20 50 6c 61 63 65 20 61 ze.**.** Place a
1cf70 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e "soft" limit on
1cf80 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 the amount of h
1cf90 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 eap memory that
1cfa0 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 may be allocated
1cfb0 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65 2e 20 20 .** by SQLite.
1cfc0 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 If an internal a
1cfd0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 llocation is req
1cfe0 75 65 73 74 65 64 20 0a 2a 2a 20 74 68 61 74 20 uested .** that
1cff0 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 would exceed the
1d000 20 73 70 65 63 69 66 69 65 64 20 6c 69 6d 69 74 specified limit
1d010 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 , [sqlite3_relea
1d020 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 0a se_memory()] is.
1d030 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f ** invoked one o
1d040 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 r more times to
1d050 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 free up some spa
1d060 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c ce before the al
1d070 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d location.** is m
1d080 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c ade..**.** The l
1d090 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 imit is called "
1d0a0 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 69 soft", because i
1d0b0 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 f [sqlite3_relea
1d0c0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 63 61 6e se_memory()] can
1d0d0 6e 6f 74 0a 2a 2a 20 66 72 65 65 20 73 75 66 66 not.** free suff
1d0e0 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f icient memory to
1d0f0 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d prevent the lim
1d100 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 it from being ex
1d110 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d ceeded,.** the m
1d120 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 emory is allocat
1d130 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 ed anyway and th
1d140 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 e current operat
1d150 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a ion proceeds..**
1d160 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f .** A negative o
1d170 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 r zero value for
1d180 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 N means that th
1d190 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 ere is no soft h
1d1a0 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a eap limit and.**
1d1b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 [sqlite3_releas
1d1c0 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c e_memory()] will
1d1d0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 only be called
1d1e0 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 when memory is e
1d1f0 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65 xhausted..** The
1d200 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 default value f
1d210 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 or the soft heap
1d220 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a limit is zero..
1d230 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b **.** SQLite mak
1d240 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74 es a best effort
1d250 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f to honor the so
1d260 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 ft heap limit.
1d270 42 75 74 20 69 66 20 69 74 0a 2a 2a 20 69 73 20 But if it.** is
1d280 75 6e 61 62 6c 65 20 74 6f 20 72 65 64 75 63 65 unable to reduce
1d290 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 62 65 memory usage be
1d2a0 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 6c 69 6d low the soft lim
1d2b0 69 74 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 it, execution wi
1d2c0 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 ll.** continue w
1d2d0 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 ithout error or
1d2e0 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 notification. T
1d2f0 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c his is why the l
1d300 69 6d 69 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c imit is .** call
1d310 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 ed a "soft" limi
1d320 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f t. It is adviso
1d330 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 ry only..**.** T
1d340 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d he soft heap lim
1d350 69 74 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 it is implemente
1d360 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c d using the [sql
1d370 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 ite3_memory_alar
1d380 6d 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 m()].** interfac
1d390 65 2e 20 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c e. Only a singl
1d3a0 65 20 6d 65 6d 6f 72 79 20 61 6c 61 72 6d 20 69 e memory alarm i
1d3b0 73 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 s available in t
1d3c0 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 69 6d he default.** im
1d3d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 plementation. T
1d3e0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 his means that i
1d3f0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
1d400 6e 20 61 6c 73 6f 20 75 73 65 73 20 74 68 65 0a n also uses the.
1d410 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 61 72 6d 20 ** memory alarm
1d420 69 6e 74 65 72 66 61 63 65 20 69 74 20 77 69 6c interface it wil
1d430 6c 20 69 6e 74 65 72 66 65 72 65 20 77 69 74 68 l interfere with
1d440 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f the operation o
1d450 66 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65 f the.** soft he
1d460 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 75 6e 64 ap limit and und
1d470 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 20 efined behavior
1d480 77 69 6c 6c 20 72 65 73 75 6c 74 2e 20 20 0a 2a will result. .*
1d490 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 *.** Prior to SQ
1d4a0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
1d4b0 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .0, this routine
1d4c0 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 only constraine
1d4d0 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 d the memory.**
1d4e0 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 allocated by a s
1d4f0 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 ingle thread - t
1d500 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
1d510 6e 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 n which this rou
1d520 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 tine.** runs. B
1d530 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 eginning with SQ
1d540 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
1d550 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 .0, the soft hea
1d560 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 p limit is.** ap
1d570 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 plied to all thr
1d580 65 61 64 73 2e 20 20 54 68 65 20 76 61 6c 75 65 eads. The value
1d590 20 73 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 specified for t
1d5a0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d he soft heap lim
1d5b0 69 74 0a 2a 2a 20 69 73 20 61 6e 20 62 6f 75 6e it.** is an boun
1d5c0 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d d on the total m
1d5d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1d5e0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 for all threads
1d5f0 2e 20 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e . In.** version
1d600 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20 3.5.0 there is
1d610 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 no mechanism for
1d620 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65 limiting the he
1d630 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 ap usage for.**
1d640 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65 61 individual threa
1d650 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 ds..*/.void sqli
1d660 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 te3_soft_heap_li
1d670 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a mit(int);../*.**
1d680 20 43 41 50 49 33 52 45 46 3a 20 20 45 78 74 72 CAPI3REF: Extr
1d690 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f act Metadata Abo
1d6a0 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 ut A Column Of A
1d6b0 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 69 Table.**.** Thi
1d6c0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74 s routine.** ret
1d6d0 75 72 6e 73 20 6d 65 74 61 2d 64 61 74 61 20 61 urns meta-data a
1d6e0 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20 bout a specific
1d6f0 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 column of a spec
1d700 69 66 69 63 20 64 61 74 61 62 61 73 65 0a 2a 2a ific database.**
1d710 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c table accessibl
1d720 65 20 75 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e e using the conn
1d730 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 70 61 ection handle pa
1d740 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 ssed as the firs
1d750 74 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 61 t function .** a
1d760 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 rgument..**.** T
1d770 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 he column is ide
1d780 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 ntified by the s
1d790 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 econd, third and
1d7a0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
1d7b0 72 73 20 74 6f 20 0a 2a 2a 20 74 68 69 73 20 66 rs to .** this f
1d7c0 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 unction. The sec
1d7d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
1d7e0 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 either the name
1d7f0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
1d800 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 .** (i.e. "main"
1d810 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 , "temp" or an a
1d820 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
1d830 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 ) containing the
1d840 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 specified.** ta
1d850 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 ble or NULL. If
1d860 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e it is NULL, then
1d870 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 all attached da
1d880 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72 tabases are sear
1d890 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 ched.** for the
1d8a0 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 table using the
1d8b0 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 61 same algorithm a
1d8c0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 s the database e
1d8d0 6e 67 69 6e 65 20 75 73 65 73 20 74 6f 20 0a 2a ngine uses to .*
1d8e0 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c * resolve unqual
1d8f0 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 ified table refe
1d900 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 rences..**.** Th
1d910 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 e third and four
1d920 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f th parameters to
1d930 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 this function a
1d940 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 re the table and
1d950 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 column .** name
1d960 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 of the desired
1d970 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 column, respecti
1d980 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 vely. Neither of
1d990 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 these parameter
1d9a0 73 20 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c s .** may be NUL
1d9b0 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 20 69 6e L..**.** Meta in
1d9c0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 74 formation is ret
1d9d0 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 urned by writing
1d9e0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c to the memory l
1d9f0 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 ocations passed
1da00 61 73 0a 2a 2a 20 74 68 65 20 35 74 68 20 61 6e as.** the 5th an
1da10 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 d subsequent par
1da20 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 ameters to this
1da30 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 function. Any of
1da40 20 74 68 65 73 65 20 0a 2a 2a 20 61 72 67 75 6d these .** argum
1da50 65 6e 74 73 20 6d 61 79 20 62 65 20 4e 55 4c 4c ents may be NULL
1da60 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 , in which case
1da70 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
1da80 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 g element of met
1da90 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f a .** informatio
1daa0 6e 20 69 73 20 6f 6d 6d 69 74 74 65 64 2e 0a 2a n is ommitted..*
1dab0 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 50 61 *.** <pre>.** Pa
1dac0 72 61 6d 65 74 65 72 20 20 20 20 20 4f 75 74 70 rameter Outp
1dad0 75 74 20 54 79 70 65 20 20 20 20 20 20 44 65 73 ut Type Des
1dae0 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d cription.** ----
1daf0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1db00 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a ---------------.
1db10 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20 20 20 20 **.** 5th
1db20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 const char*
1db30 20 20 20 20 20 44 61 74 61 20 74 79 70 65 0a 2a Data type.*
1db40 2a 20 20 20 36 74 68 20 20 20 20 20 20 20 20 20 * 6th
1db50 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20 const char*
1db60 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 66 Name of the def
1db70 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 ault collation s
1db80 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20 20 37 74 equence .** 7t
1db90 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 h int
1dba0 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20 True
1dbb0 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 68 61 if the column ha
1dbc0 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e s a NOT NULL con
1dbd0 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20 38 74 68 straint.** 8th
1dbe0 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 int
1dbf0 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69 True i
1dc00 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 f the column is
1dc10 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d part of the PRIM
1dc20 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20 39 74 68 ARY KEY.** 9th
1dc30 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 int
1dc40 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69 True i
1dc50 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 f the column is
1dc60 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a AUTOINCREMENT.**
1dc70 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a </pre>.**.**.**
1dc80 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e The memory poin
1dc90 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 ted to by the ch
1dca0 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 aracter pointers
1dcb0 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 returned for th
1dcc0 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f e .** declaratio
1dcd0 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 n type and colla
1dce0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 tion sequence is
1dcf0 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 valid only unti
1dd00 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a 2a 20 63 l the next .** c
1dd10 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71 6c 69 74 all to any sqlit
1dd20 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a e API function..
1dd30 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 **.** If the spe
1dd40 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 cified table is
1dd50 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c actually a view,
1dd60 20 74 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 69 then an error i
1dd70 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
1dd80 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 * If the specifi
1dd90 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f ed column is "ro
1dda0 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 wid", "oid" or "
1ddb0 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 20 _rowid_" and an
1ddc0 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50 52 49 4d .** INTEGER PRIM
1ddd0 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 68 ARY KEY column h
1dde0 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 as been explicit
1ddf0 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 ly declared, the
1de00 6e 20 74 68 65 20 6f 75 74 70 75 74 20 0a 2a 2a n the output .**
1de10 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 parameters are
1de20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c set for the expl
1de30 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 icitly declared
1de40 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 column. If there
1de50 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 is no.** explic
1de60 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 49 50 itly declared IP
1de70 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 K column, then t
1de80 68 65 20 6f 75 74 70 75 74 20 70 61 72 61 6d 65 he output parame
1de90 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73 20 ters are set as
1dea0 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a .** follows:.**.
1deb0 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 ** <pre>.**
1dec0 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 data type: "INTE
1ded0 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c GER".** coll
1dee0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 ation sequence:
1def0 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 "BINARY".**
1df00 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 not null: 0.**
1df10 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 primary key:
1df20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 1.** auto in
1df30 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f crement: 0.** </
1df40 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 pre>.**.** This
1df50 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 function may loa
1df60 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 d one or more sc
1df70 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 hemas from datab
1df80 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e ase files. If an
1df90 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 .** error occurs
1dfa0 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f during this pro
1dfb0 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 cess, or if the
1dfc0 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 requested table
1dfd0 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e or column.** can
1dfe0 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e not be found, an
1dff0 20 53 51 4c 49 54 45 20 65 72 72 6f 72 20 63 6f SQLITE error co
1e000 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 de is returned a
1e010 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 nd an error mess
1e020 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69 6e 20 74 age.** left in t
1e030 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 he database hand
1e040 6c 65 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 le (to be retrie
1e050 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 ved using sqlite
1e060 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 3_errmsg())..**.
1e070 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f ** This API is o
1e080 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 nly available if
1e090 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 the library was
1e0a0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
1e0b0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 he.** SQLITE_ENA
1e0c0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 BLE_COLUMN_METAD
1e0d0 41 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72 ATA preprocessor
1e0e0 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e symbol defined.
1e0f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
1e100 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 table_column_met
1e110 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 adata(. sqlite3
1e120 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
1e130 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 /* Connecti
1e140 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 on handle */. c
1e150 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 onst char *zDbNa
1e160 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 me, /* Da
1e170 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e tabase name or N
1e180 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ULL */. const c
1e190 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c har *zTableName,
1e1a0 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 /* Table na
1e1b0 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 me */. const ch
1e1c0 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c ar *zColumnName,
1e1d0 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 /* Column na
1e1e0 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e me */. char con
1e1f0 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c st **pzDataType,
1e200 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 /* OUTPUT: D
1e210 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 eclared data typ
1e220 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 e */. char cons
1e230 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 t **pzCollSeq,
1e240 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f /* OUTPUT: Co
1e250 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
1e260 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a name */. int *
1e270 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 pNotNull,
1e280 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 /* OUTPUT
1e290 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 : True if NOT NU
1e2a0 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 LL constraint ex
1e2b0 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 ists */. int *p
1e2c0 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 PrimaryKey,
1e2d0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a /* OUTPUT:
1e2e0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 True if column
1e2f0 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 part of PK */.
1e300 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 int *pAutoinc
1e310 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f /* O
1e320 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 UTPUT: True if c
1e330 6f 6c 75 6d 73 20 69 73 20 61 75 74 6f 2d 69 6e olums is auto-in
1e340 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f crement */.);../
1e350 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c *.** CAPI3REF: L
1e360 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e oad An Extension
1e370 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d 70 74 20 74 .**.** Attempt t
1e380 6f 20 6c 6f 61 64 20 61 6e 20 53 51 4c 69 74 65 o load an SQLite
1e390 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 extension libra
1e3a0 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 ry contained in
1e3b0 74 68 65 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c the file.** zFil
1e3c0 65 2e 20 20 54 68 65 20 65 6e 74 72 79 20 70 6f e. The entry po
1e3d0 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20 20 7a int is zProc. z
1e3e0 50 72 6f 63 20 6d 61 79 20 62 65 20 30 20 69 6e Proc may be 0 in
1e3f0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 0a which case the.
1e400 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 ** name of the e
1e410 6e 74 72 79 20 70 6f 69 6e 74 20 64 65 66 61 75 ntry point defau
1e420 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f lts to "sqlite3_
1e430 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e extension_init".
1e440 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 5b 53 .**.** Return [S
1e450 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
1e460 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 cess and [SQLITE
1e470 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 _ERROR] if somet
1e480 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e hing goes wrong.
1e490 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 .**.** If an err
1e4a0 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a or occurs and pz
1e4b0 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c ErrMsg is not 0,
1e4c0 20 74 68 65 6e 20 66 69 6c 6c 20 2a 70 7a 45 72 then fill *pzEr
1e4d0 72 4d 73 67 20 77 69 74 68 20 0a 2a 2a 20 65 72 rMsg with .** er
1e4e0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 ror message text
1e4f0 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 . The calling f
1e500 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 unction should f
1e510 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a ree this memory.
1e520 2a 2a 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 ** by calling [s
1e530 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
1e540 2a 2a 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20 **.** Extension
1e550 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 loading must be
1e560 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 enabled using [s
1e570 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f qlite3_enable_lo
1e580 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a ad_extension()].
1e590 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c ** prior to call
1e5a0 69 6e 67 20 74 68 69 73 20 41 50 49 20 6f 72 20 ing this API or
1e5b0 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 an error will be
1e5c0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e returned..*/.in
1e5d0 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 t sqlite3_load_e
1e5e0 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 xtension(. sqli
1e5f0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
1e600 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 /* Load the ex
1e610 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 tension into thi
1e620 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 s database conne
1e630 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 ction */. const
1e640 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 char *zFile,
1e650 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 /* Name of the
1e660 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 shared library c
1e670 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 ontaining extens
1e680 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ion */. const c
1e690 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f har *zProc, /
1e6a0 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 * Entry point.
1e6b0 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 Derived from zFi
1e6c0 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 le if 0 */. cha
1e6d0 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 r **pzErrMsg
1e6e0 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 /* Put error
1e6f0 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20 message here if
1e700 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a not 0 */.);../*.
1e710 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e ** CAPI3REF: En
1e720 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 able Or Disable
1e730 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e Extension Loadin
1e740 67 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f g.**.** So as no
1e750 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 t to open securi
1e760 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 ty holes in olde
1e770 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 r applications t
1e780 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 hat are.** unpre
1e790 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 pared to deal wi
1e7a0 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 th extension loa
1e7b0 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d ding, and as a m
1e7c0 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e eans of disablin
1e7d0 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c g.** extension l
1e7e0 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 oading while eva
1e7f0 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 luating user-ent
1e800 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f ered SQL, the fo
1e810 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50 49 20 69 llowing.** API i
1e820 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 s provided to tu
1e830 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f rn the [sqlite3_
1e840 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
1e850 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 ] mechanism on a
1e860 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20 49 74 20 69 nd.** off. It i
1e870 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 s off by default
1e880 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 . See ticket #1
1e890 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 20 863..**.** Call
1e8a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 this routine wit
1e8b0 68 20 6f 6e 6f 66 66 3d 3d 31 20 74 6f 20 74 75 h onoff==1 to tu
1e8c0 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 rn extension loa
1e8d0 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61 6e 64 20 63 ding on.** and c
1e8e0 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 all it with onof
1e8f0 66 3d 3d 30 20 74 6f 20 74 75 72 6e 20 69 74 20 f==0 to turn it
1e900 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a back off again..
1e910 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 */.int sqlite3_e
1e920 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e nable_load_exten
1e930 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 sion(sqlite3 *db
1e940 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f , int onoff);../
1e950 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
1e960 61 6b 65 20 41 72 72 61 6e 67 65 6d 65 6e 74 73 ake Arrangements
1e970 20 54 6f 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c To Automaticall
1e980 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 y Load An Extens
1e990 69 6f 6e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 ion.**.** Regist
1e9a0 65 72 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 er an extension
1e9b0 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 entry point that
1e9c0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c is automaticall
1e9d0 79 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 y invoked.** whe
1e9e0 6e 65 76 65 72 20 61 20 6e 65 77 20 64 61 74 61 never a new data
1e9f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1ea00 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a is opened using.
1ea10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ** [sqlite3_open
1ea20 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
1ea30 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c en16()], or [sql
1ea40 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e ite3_open_v2()].
1ea50 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 .**.** This API
1ea60 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 can be invoked a
1ea70 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75 t program startu
1ea80 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 p in order to re
1ea90 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 gister.** one or
1eaa0 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79 more statically
1eab0 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f linked extensio
1eac0 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 ns that will be
1ead0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 available.** to
1eae0 61 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65 all new database
1eaf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a connections..**
1eb00 0a 2a 2a 20 44 75 70 6c 69 63 61 74 65 20 65 78 .** Duplicate ex
1eb10 74 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 tensions are det
1eb20 65 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 ected so calling
1eb30 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 this routine mu
1eb40 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 ltiple.** times
1eb50 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 with the same ex
1eb60 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c tension is harml
1eb70 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ess..**.** This
1eb80 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 routine stores a
1eb90 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
1eba0 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 extension in an
1ebb0 61 72 72 61 79 0a 2a 2a 20 74 68 61 74 20 69 73 array.** that is
1ebc0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d obtained from m
1ebd0 61 6c 6c 6f 63 28 29 2e 20 20 49 66 20 79 6f 75 alloc(). If you
1ebe0 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 run a memory le
1ebf0 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20 6f 6e ak.** checker on
1ec00 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e your program an
1ec10 64 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c d it reports a l
1ec20 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74 eak because of t
1ec30 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20 74 68 his.** array, th
1ec40 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 en invoke [sqlit
1ec50 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78 74 e3_automatic_ext
1ec60 65 6e 73 69 6f 6e 5f 72 65 73 65 74 28 29 5d 20 ension_reset()]
1ec70 70 72 69 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 prior.** to shut
1ec80 64 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 down to free the
1ec90 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 memory..**.** A
1eca0 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 utomatic extensi
1ecb0 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 ons apply across
1ecc0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a all threads..**
1ecd0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
1ece0 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 ce is experiment
1ecf0 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 al and is subjec
1ed00 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a t to change or.*
1ed10 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 * removal in fut
1ed20 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
1ed30 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 SQLite..*/.int s
1ed40 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 qlite3_auto_exte
1ed50 6e 73 69 6f 6e 28 76 6f 69 64 20 2a 78 45 6e 74 nsion(void *xEnt
1ed60 72 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a ryPoint);.../*.*
1ed70 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
1ed80 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 t Automatic Exte
1ed90 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a nsion Loading.**
1eda0 0a 2a 2a 20 44 69 73 61 62 6c 65 20 61 6c 6c 20 .** Disable all
1edb0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 previously regis
1edc0 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63 20 tered automatic
1edd0 65 78 74 65 6e 73 69 6f 6e 73 2e 20 20 54 68 69 extensions. Thi
1ede0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 s.** routine und
1edf0 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f oes the effect o
1ee00 66 20 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c f all prior [sql
1ee10 69 74 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 ite3_automatic_e
1ee20 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63 xtension()].** c
1ee30 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 alls..**.** This
1ee40 20 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20 61 call disabled a
1ee50 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 utomatic extensi
1ee60 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 ons in all threa
1ee70 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 ds..**.** This i
1ee80 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 nterface is expe
1ee90 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 rimental and is
1eea0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
1eeb0 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 e or.** removal
1eec0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
1eed0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f es of SQLite..*/
1eee0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
1eef0 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 set_auto_extensi
1ef00 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a on(void);.../*.*
1ef10 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 ***** EXPERIMENT
1ef20 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 AL - subject to
1ef30 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e change without n
1ef40 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a otice **********
1ef50 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ****.**.** The i
1ef60 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 nterface to the
1ef70 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
1ef80 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 chanism is curre
1ef90 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a ntly considered.
1efa0 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d ** to be experim
1efb0 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 ental. The inte
1efc0 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e rface might chan
1efd0 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 ge in incompatib
1efe0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 le ways..** If t
1eff0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d his is a problem
1f000 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 for you, do not
1f010 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 use the interfa
1f020 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e ce at this time.
1f030 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
1f040 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
1f050 63 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65 chanism stablize
1f060 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 s, we will decla
1f070 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 re the.** interf
1f080 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f ace fixed, suppo
1f090 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 rt it indefinite
1f0a0 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 ly, and remove t
1f0b0 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a his comment..*/.
1f0c0 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 ./*.** Structure
1f0d0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 s used by the vi
1f0e0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 rtual table inte
1f0f0 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 rface.*/.typedef
1f100 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
1f110 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 vtab sqlite3_vta
1f120 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 b;.typedef struc
1f130 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f t sqlite3_index_
1f140 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 info sqlite3_ind
1f150 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 ex_info;.typedef
1f160 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
1f170 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 vtab_cursor sqli
1f180 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b te3_vtab_cursor;
1f190 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
1f1a0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 sqlite3_module s
1f1b0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a qlite3_module;..
1f1c0 2f 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69 /*.** A module i
1f1d0 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72 s a class of vir
1f1e0 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61 tual tables. Ea
1f1f0 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66 ch module is def
1f200 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e ined.** by an in
1f210 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f stance of the fo
1f220 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 llowing structur
1f230 65 2e 20 20 54 68 69 73 20 73 74 72 75 63 74 75 e. This structu
1f240 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d re consists.** m
1f250 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 ostly of methods
1f260 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e for the module.
1f270 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 .*/.struct sqlit
1f280 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e e3_module {. in
1f290 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e t iVersion;. in
1f2a0 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c t (*xCreate)(sql
1f2b0 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 ite3*, void *pAu
1f2c0 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 x,.
1f2d0 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 int argc, cons
1f2e0 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 t char *const*ar
1f2f0 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 gv,.
1f300 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 sqlite3_vtab
1f310 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a **ppVTab, char**
1f320 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e );. int (*xConn
1f330 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 ect)(sqlite3*, v
1f340 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 oid *pAux,.
1f350 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 int ar
1f360 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a gc, const char *
1f370 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 const*argv,.
1f380 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 sqlit
1f390 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 e3_vtab **ppVTab
1f3a0 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 , char**);. int
1f3b0 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 (*xBestIndex)(s
1f3c0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
1f3d0 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 ab, sqlite3_inde
1f3e0 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 x_info*);. int
1f3f0 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 (*xDisconnect)(s
1f400 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
1f410 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 ab);. int (*xDe
1f420 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 stroy)(sqlite3_v
1f430 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 tab *pVTab);. i
1f440 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 nt (*xOpen)(sqli
1f450 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c te3_vtab *pVTab,
1f460 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 sqlite3_vtab_cu
1f470 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 rsor **ppCursor)
1f480 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 ;. int (*xClose
1f490 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 )(sqlite3_vtab_c
1f4a0 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 ursor*);. int (
1f4b0 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 *xFilter)(sqlite
1f4c0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 3_vtab_cursor*,
1f4d0 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 int idxNum, cons
1f4e0 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a t char *idxStr,.
1f4f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1f500 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 int argc, sqlite
1f510 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 3_value **argv);
1f520 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 . int (*xNext)(
1f530 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
1f540 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sor*);. int (*x
1f550 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 Eof)(sqlite3_vta
1f560 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e b_cursor*);. in
1f570 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c t (*xColumn)(sql
1f580 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
1f590 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 *, sqlite3_conte
1f5a0 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 xt*, int);. int
1f5b0 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 (*xRowid)(sqlit
1f5c0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c e3_vtab_cursor*,
1f5d0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
1f5e0 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 pRowid);. int (
1f5f0 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 *xUpdate)(sqlite
1f600 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 3_vtab *, int, s
1f610 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c qlite3_value **,
1f620 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
1f630 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 );. int (*xBegi
1f640 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 n)(sqlite3_vtab
1f650 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 *pVTab);. int (
1f660 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f *xSync)(sqlite3_
1f670 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
1f680 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 int (*xCommit)(s
1f690 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
1f6a0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f ab);. int (*xRo
1f6b0 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f llback)(sqlite3_
1f6c0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
1f6d0 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 int (*xFindFunct
1f6e0 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ion)(sqlite3_vta
1f6f0 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 b *pVtab, int nA
1f700 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a rg, const char *
1f710 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 zName,.
1f720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f vo
1f730 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 id (**pxFunc)(sq
1f740 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
1f750 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
1f760 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 **),.
1f770 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 void
1f780 20 2a 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69 6e **ppArg);.. in
1f790 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c t (*xRename)(sql
1f7a0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 ite3_vtab *pVtab
1f7b0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
1f7c0 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 ew);.};../*.** T
1f7d0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 he sqlite3_index
1f7e0 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 _info structure
1f7f0 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63 and its substruc
1f800 74 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f tures is used to
1f810 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 .** pass informa
1f820 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 tion into and re
1f830 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 ceive the reply
1f840 66 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e from the xBestIn
1f850 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 dex.** method of
1f860 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 an sqlite3_modu
1f870 6c 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 le. The fields
1f880 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a under **Inputs**
1f890 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 are the.** inpu
1f8a0 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 ts to xBestIndex
1f8b0 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e and are read-on
1f8c0 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 ly. xBestIndex
1f8d0 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 inserts its.** r
1f8e0 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 esults into the
1f8f0 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c **Outputs** fiel
1f900 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 ds..**.** The aC
1f910 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 onstraint[] arra
1f920 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 y records WHERE
1f930 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e clause constrain
1f940 74 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 ts of the.** for
1f950 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20 m:.**.**
1f960 20 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a column OP expr.
1f970 2a 2a 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69 **.** Where OP i
1f980 73 20 3d 2c 20 3c 2c 20 3c 3d 2c 20 3e 2c 20 6f s =, <, <=, >, o
1f990 72 20 3e 3d 2e 20 20 54 68 65 20 70 61 72 74 69 r >=. The parti
1f9a0 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 cular operator i
1f9b0 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 s stored.** in a
1f9c0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e Constraint[].op.
1f9d0 20 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 The index of t
1f9e0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f he column is sto
1f9f0 72 65 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 red in .** aCons
1fa00 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e traint[].iColumn
1fa10 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d . aConstraint[]
1fa20 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 .usable is TRUE
1fa30 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f if the.** expr o
1fa40 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 n the right-hand
1fa50 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 side can be eva
1fa60 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 luated (and thus
1fa70 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a the constraint.
1fa80 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e ** is usable) an
1fa90 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 d false if it ca
1faa0 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nnot..**.** The
1fab0 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 optimizer automa
1fac0 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 tically inverts
1fad0 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 terms of the for
1fae0 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d m "expr OP colum
1faf0 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 n".** and makes
1fb00 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 other simplifica
1fb10 74 69 6e 6f 73 20 74 6f 20 74 68 65 20 57 48 45 tinos to the WHE
1fb20 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 RE clause in an
1fb30 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 attempt to.** ge
1fb40 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 t as many WHERE
1fb50 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 clause terms int
1fb60 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e o the form shown
1fb70 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 above as possib
1fb80 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 le..** The aCons
1fb90 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f traint[] array o
1fba0 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 nly reports WHER
1fbb0 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 E clause terms i
1fbc0 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a n the correct.**
1fbd0 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 form that refer
1fbe0 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c to the particul
1fbf0 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 ar virtual table
1fc00 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a being queried..
1fc10 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f **.** Informatio
1fc20 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 n about the ORDE
1fc30 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 R BY clause is s
1fc40 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 tored in aOrderB
1fc50 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 y[]..** Each ter
1fc60 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 m of aOrderBy re
1fc70 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f cords a column o
1fc80 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 f the ORDER BY c
1fc90 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 lause..**.** The
1fca0 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 xBestIndex meth
1fcb0 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f od must fill aCo
1fcc0 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 nstraintUsage[]
1fcd0 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e with information
1fce0 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 .** about what p
1fcf0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 arameters to pas
1fd00 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 s to xFilter. I
1fd10 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 f argvIndex>0 th
1fd20 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d en.** the right-
1fd30 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 hand side of the
1fd40 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 corresponding a
1fd50 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 Constraint[] is
1fd60 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 evaluated.** and
1fd70 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 becomes the arg
1fd80 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 vIndex-th entry
1fd90 69 6e 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f in argv. If aCo
1fda0 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e nstraintUsage[].
1fdb0 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c omit.** is true,
1fdc0 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 then the constr
1fdd0 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 aint is assumed
1fde0 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 to be fully hand
1fdf0 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 led by the.** vi
1fe00 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 rtual table and
1fe10 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 is not checked a
1fe20 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a gain by SQLite..
1fe30 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d **.** The idxNum
1fe40 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 and idxPtr valu
1fe50 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 es are recorded
1fe60 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 and passed into
1fe70 78 46 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 xFilter..** sqli
1fe80 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 75 73 te3_free() is us
1fe90 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 ed to free idxPt
1fea0 72 20 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49 r if needToFreeI
1feb0 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a dxPtr is true..*
1fec0 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 *.** The orderBy
1fed0 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 Consumed means t
1fee0 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 hat output from
1fef0 78 46 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 xFilter will occ
1ff00 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 ur in.** the cor
1ff10 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 rect order to sa
1ff20 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 tisfy the ORDER
1ff30 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 BY clause so tha
1ff40 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a t no separate.**
1ff50 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 sorting step is
1ff60 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a required..**.**
1ff70 20 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f The estimatedCo
1ff80 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 st value is an e
1ff90 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 stimate of the c
1ffa0 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 ost of doing the
1ffb0 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c .** particular l
1ffc0 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 ookup. A full s
1ffd0 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 can of a table w
1ffe0 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 ith N entries sh
1fff0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 ould have.** a c
20000 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e ost of N. A bin
20010 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 ary search of a
20020 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 table of N entri
20030 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 es should have a
20040 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 .** cost of appr
20050 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 oximately log(N)
20060 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 ..*/.struct sqli
20070 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b te3_index_info {
20080 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a . /* Inputs */.
20090 20 20 63 6f 6e 73 74 20 69 6e 74 20 6e 43 6f 6e const int nCon
200a0 73 74 72 61 69 6e 74 3b 20 20 20 20 20 2f 2a 20 straint; /*
200b0 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 Number of entrie
200c0 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 s in aConstraint
200d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 */. const stru
200e0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 ct sqlite3_index
200f0 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 _constraint {.
20100 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 int iColumn;
20110 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
20120 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 Column on left-h
20130 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 and side of cons
20140 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 traint */. u
20150 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b nsigned char op;
20160 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 /* Cons
20170 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 traint operator
20180 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 */. unsigned
20190 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 char usable;
201a0 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 /* True if thi
201b0 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 s constraint is
201c0 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 usable */. i
201d0 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 nt iTermOffset;
201e0 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 /* Used
201f0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 internally - xB
20200 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 estIndex should
20210 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 63 ignore */. } *c
20220 6f 6e 73 74 20 61 43 6f 6e 73 74 72 61 69 6e 74 onst aConstraint
20230 3b 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 ; /* Table
20240 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 of WHERE clause
20250 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 constraints */.
20260 20 63 6f 6e 73 74 20 69 6e 74 20 6e 4f 72 64 65 const int nOrde
20270 72 42 79 3b 20 20 20 20 20 20 20 20 2f 2a 20 4e rBy; /* N
20280 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 umber of terms i
20290 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 n the ORDER BY c
202a0 6c 61 75 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 lause */. const
202b0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
202c0 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a index_orderby {.
202d0 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e int iColumn
202e0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f ; /
202f0 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 * Column number
20300 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 */. unsigned
20310 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 char desc;
20320 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 /* True for DE
20330 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 SC. False for A
20340 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73 SC. */. } *cons
20350 74 20 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 t aOrderBy;
20360 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 /* The ORDER
20370 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 0a 20 BY clause */..
20380 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 /* Outputs */.
20390 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
203a0 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 index_constraint
203b0 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 _usage {. int
203c0 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 argvIndex;
203d0 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 /* if >0,
203e0 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61 constraint is pa
203f0 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46 rt of argv to xF
20400 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 ilter */. uns
20410 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b igned char omit;
20420 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 /* Do not
20430 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20 code a test for
20440 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 this constraint
20450 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74 20 61 43 */. } *const aC
20460 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a onstraintUsage;.
20470 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 int idxNum;
20480 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
20490 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 Number used to i
204a0 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 dentify the inde
204b0 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 x */. char *idx
204c0 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 Str;
204d0 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 /* String, pos
204e0 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 sibly obtained f
204f0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c rom sqlite3_mall
20500 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 oc */. int need
20510 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 ToFreeIdxStr;
20520 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 /* Free idxSt
20530 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f r using sqlite3_
20540 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a free() if true *
20550 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 /. int orderByC
20560 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f onsumed; /
20570 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 * True if output
20580 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 is already orde
20590 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 red */. double
205a0 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 estimatedCost;
205b0 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 /* Estimated
205c0 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 cost of using t
205d0 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a his index */.};.
205e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
205f0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f NDEX_CONSTRAINT_
20600 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 EQ 2.#define
20610 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e SQLITE_INDEX_CON
20620 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a STRAINT_GT 4.
20630 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
20640 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f NDEX_CONSTRAINT_
20650 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 LE 8.#define
20660 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e SQLITE_INDEX_CON
20670 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 STRAINT_LT 16
20680 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20690 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
206a0 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e _GE 32.#defin
206b0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 e SQLITE_INDEX_C
206c0 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 ONSTRAINT_MATCH
206d0 36 34 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 64../*.** This r
206e0 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 outine is used t
206f0 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 o register a new
20700 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 77 69 74 module name wit
20710 68 20 61 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 63 h an SQLite.** c
20720 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 onnection. Modu
20730 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 le names must be
20740 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f registered befo
20750 72 65 20 63 72 65 61 74 69 6e 67 20 6e 65 77 0a re creating new.
20760 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 ** virtual table
20770 73 20 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c s on the module,
20780 20 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 or before using
20790 20 70 72 65 65 78 69 73 74 69 6e 67 20 76 69 72 preexisting vir
207a0 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 73 20 6f tual.** tables o
207b0 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f f the module..*/
207c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
207d0 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 ate_module(. sq
207e0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
207f0 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 /* SQLi
20800 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f te connection to
20810 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 register module
20820 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 with */. const
20830 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 char *zName,
20840 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 /* Name of
20850 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 the module */.
20860 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d const sqlite3_m
20870 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d odule *, /* M
20880 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d ethods for the m
20890 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 odule */. void
208a0 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *
208b0 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 /* Client
208c0 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 data for xCreate
208d0 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a /xConnect */.);.
208e0 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 ./*.** This rout
208f0 69 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c ine is identical
20900 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
20910 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 create_module()
20920 6d 65 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a method above,.**
20930 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 except that it
20940 61 6c 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63 allows a destruc
20950 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 tor function to
20960 62 65 20 73 70 65 63 69 66 69 65 64 2e 20 49 74 be specified. It
20970 20 69 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 is.** even more
20980 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68 experimental th
20990 61 6e 20 74 68 65 20 72 65 73 74 20 6f 66 20 74 an the rest of t
209a0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 he virtual table
209b0 73 20 41 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 s API..*/.int sq
209c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 lite3_create_mod
209d0 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 ule_v2(. sqlite
209e0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
209f0 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 /* SQLite c
20a00 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 onnection to reg
20a10 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 ister module wit
20a20 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 h */. const cha
20a30 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 r *zName,
20a40 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 /* Name of the
20a50 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e module */. con
20a60 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c st sqlite3_modul
20a70 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f e *, /* Metho
20a80 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c ds for the modul
20a90 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 e */. void *,
20aa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20ab0 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 /* Client data
20ac0 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f for xCreate/xCo
20ad0 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 nnect */. void(
20ae0 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a *xDestroy)(void*
20af0 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 ) /* Module
20b00 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 destructor funct
20b10 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a ion */.);../*.**
20b20 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d Every module im
20b30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 plementation use
20b40 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 s a subclass of
20b50 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 the following st
20b60 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 ructure.** to de
20b70 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75 scribe a particu
20b80 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 lar instance of
20b90 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 the module. Eac
20ba0 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a h subclass will.
20bb0 2a 2a 20 62 65 20 74 61 79 6c 6f 72 65 64 20 74 ** be taylored t
20bc0 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e o the specific n
20bd0 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 eeds of the modu
20be0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
20bf0 6e 2e 20 20 20 54 68 65 0a 2a 2a 20 70 75 72 70 n. The.** purp
20c00 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 ose of this supe
20c10 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 rclass is to def
20c20 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c ine certain fiel
20c30 64 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 6d ds that are comm
20c40 6f 6e 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 on.** to all mod
20c50 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ule implementati
20c60 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 ons..**.** Virtu
20c70 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 al tables method
20c80 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 s can set an err
20c90 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 or message by as
20ca0 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 signing a.** str
20cb0 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ing obtained fro
20cc0 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 m sqlite3_mprint
20cd0 66 28 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 f() to zErrMsg.
20ce0 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 The method shou
20cf0 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 ld.** take care
20d00 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 that any prior s
20d10 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 tring is freed b
20d20 79 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 y a call to sqli
20d30 74 65 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70 72 te3_free().** pr
20d40 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 ior to assigning
20d50 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f a new string to
20d60 20 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 zErrMsg. After
20d70 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
20d80 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 ge.** is deliver
20d90 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 ed up to the cli
20da0 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c ent application,
20db0 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c the string will
20dc0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c be automaticall
20dd0 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 y.** freed by sq
20de0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 lite3_free() and
20df0 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 the zErrMsg fie
20e00 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 ld will be zeroe
20e10 64 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 d. Note.** that
20e20 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 sqlite3_mprintf
20e30 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66 () and sqlite3_f
20e40 72 65 65 28 29 20 61 72 65 20 75 73 65 64 20 6f ree() are used o
20e50 6e 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 n the zErrMsg fi
20e60 65 6c 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72 eld.** since vir
20e70 74 75 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 tual tables are
20e80 63 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 commonly impleme
20e90 6e 74 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65 nted in loadable
20ea0 20 65 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63 extensions whic
20eb0 68 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65 h.** do not have
20ec0 20 61 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74 access to sqlit
20ed0 65 33 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73 e3MPrintf() or s
20ee0 71 6c 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2f qlite3Free()..*/
20ef0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
20f00 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 vtab {. const s
20f10 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 qlite3_module *p
20f20 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 Module; /* The
20f30 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 module for this
20f40 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f virtual table */
20f50 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 . int nRef;
20f60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20f70 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 /* Used inter
20f80 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20 nally */. char
20f90 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 *zErrMsg;
20fa0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 /* Er
20fb0 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d ror message from
20fc0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 sqlite3_mprintf
20fd0 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 () */. /* Virtu
20fe0 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 al table impleme
20ff0 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 ntations will ty
21000 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 pically add addi
21010 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f tional fields */
21020 0a 7d 3b 0a 0a 2f 2a 20 45 76 65 72 79 20 6d 6f .};../* Every mo
21030 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 dule implementat
21040 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c ion uses a subcl
21050 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f ass of the follo
21060 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a wing structure.*
21070 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 * to describe cu
21080 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 rsors that point
21090 20 69 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61 into the virtua
210a0 6c 20 74 61 62 6c 65 20 61 6e 64 20 61 72 65 20 l table and are
210b0 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 used.** to loop
210c0 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 through the virt
210d0 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 ual table. Curs
210e0 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20 ors are created
210f0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f 70 using the.** xOp
21100 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 en method of the
21110 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d module. Each m
21120 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 odule implementa
21130 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 tion will define
21140 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 .** the content
21150 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 of a cursor stru
21160 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 cture to suit it
21170 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a s own needs..**.
21180 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 ** This supercla
21190 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 ss exists in ord
211a0 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 er to define fie
211b0 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f lds of the curso
211c0 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f r that.** are co
211d0 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c mmon to all impl
211e0 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a ementations..*/.
211f0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
21200 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 tab_cursor {. s
21210 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 qlite3_vtab *pVt
21220 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 ab; /* Virt
21230 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 ual table of thi
21240 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a s cursor */. /*
21250 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 Virtual table i
21260 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 mplementations w
21270 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 ill typically ad
21280 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 d additional fie
21290 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a lds */.};../*.**
212a0 20 54 68 65 20 78 43 72 65 61 74 65 20 61 6e 64 The xCreate and
212b0 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 xConnect method
212c0 73 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 73 s of a module us
212d0 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 e the following
212e0 41 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 API.** to declar
212f0 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 e the format (th
21300 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 e names and data
21310 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c types of the col
21320 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 umns) of.** the
21330 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 virtual tables t
21340 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a hey implement..*
21350 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 /.int sqlite3_de
21360 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 clare_vtab(sqlit
21370 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 e3*, const char
21380 2a 7a 43 72 65 61 74 65 54 61 62 6c 65 29 3b 0a *zCreateTable);.
21390 0a 2f 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 ./*.** Virtual t
213a0 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 ables can provid
213b0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d e alternative im
213c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
213d0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 functions.** us
213e0 69 6e 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e ing the xFindFun
213f0 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42 ction method. B
21400 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f ut global versio
21410 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 ns of those func
21420 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 tions.** must ex
21430 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ist in order to
21440 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a be overloaded..*
21450 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 *.** This API ma
21460 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 kes sure a globa
21470 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 l version of a f
21480 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 unction with a p
21490 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d articular.** nam
214a0 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 e and number of
214b0 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 parameters exist
214c0 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 s. If no such f
214d0 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a unction exists.*
214e0 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 * before this AP
214f0 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e I is called, a n
21500 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 ew function is c
21510 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 reated. The imp
21520 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f lementation.** o
21530 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 f the new functi
21540 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 on always causes
21550 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f an exception to
21560 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a be thrown. So.
21570 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 ** the new funct
21580 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 ion is not good
21590 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 for anything by
215a0 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c itself. Its onl
215b0 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 y.** purpose is
215c0 74 6f 20 62 65 20 61 20 70 6c 61 63 65 2d 68 6f to be a place-ho
215d0 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 lder function th
215e0 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f at can be overlo
215f0 61 64 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75 aded.** by virtu
21600 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a al tables..**.**
21610 20 54 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64 This API should
21620 20 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70 be considered p
21630 61 72 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 art of the virtu
21640 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 al table interfa
21650 63 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 ce,.** which is
21660 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 experimental and
21670 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
21680 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ge..*/.int sqlit
21690 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 e3_overload_func
216a0 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 tion(sqlite3*, c
216b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 onst char *zFunc
216c0 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b Name, int nArg);
216d0 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 ../*.** The inte
216e0 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 rface to the vir
216f0 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 tual-table mecha
21700 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f nism defined abo
21710 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 ve (back up.** t
21720 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 o a comment rema
21730 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 rkably similar t
21740 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 o this one) is c
21750 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 urrently conside
21760 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 red.** to be exp
21770 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 erimental. The
21780 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 interface might
21790 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 change in incomp
217a0 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 atible ways..**
217b0 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f If this is a pro
217c0 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f blem for you, do
217d0 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 not use the int
217e0 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 erface at this t
217f0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 ime..**.** When
21800 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c the virtual-tabl
21810 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 e mechanism stab
21820 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 lizes, we will d
21830 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e eclare the.** in
21840 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 terface fixed, s
21850 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 upport it indefi
21860 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f nitely, and remo
21870 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e ve this comment.
21880 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 .**.****** EXPER
21890 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 IMENTAL - subjec
218a0 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 t to change with
218b0 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a out notice *****
218c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a *********.*/../*
218d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 .** CAPI3REF: A
218e0 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 Handle To An Ope
218f0 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 41 6e 20 n BLOB.**.** An
21900 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
21910 66 6f 6c 6c 6f 77 69 6e 67 20 6f 70 61 71 75 65 following opaque
21920 20 73 74 72 75 63 74 75 72 65 20 69 73 20 75 73 structure is us
21930 65 64 20 74 6f 20 0a 2a 2a 20 72 65 70 72 65 73 ed to .** repres
21940 65 6e 74 20 61 6e 20 62 6c 6f 62 2d 68 61 6e 64 ent an blob-hand
21950 6c 65 2e 20 20 41 20 62 6c 6f 62 2d 68 61 6e 64 le. A blob-hand
21960 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79 le is created by
21970 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f .** [sqlite3_blo
21980 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 64 65 b_open()] and de
21990 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 stroyed by [sqli
219a0 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 te3_blob_close()
219b0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 ]..** The [sqlit
219c0 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 e3_blob_read()]
219d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f and [sqlite3_blo
219e0 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 b_write()] inter
219f0 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 faces.** can be
21a00 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 used to read or
21a10 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 write small subs
21a20 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 ections of the b
21a30 6c 6f 62 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c lob..** The [sql
21a40 74 69 65 33 5f 62 6c 6f 62 5f 73 69 7a 65 28 29 tie3_blob_size()
21a50 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
21a60 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 rns the size of
21a70 74 68 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62 the.** blob in b
21a80 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 ytes..*/.typedef
21a90 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
21aa0 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f blob sqlite3_blo
21ab0 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 b;../*.** CAPI3R
21ac0 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 EF: Open A BLOB
21ad0 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 For Incremental
21ae0 49 2f 4f 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 61 I/O.**.** Open a
21af0 20 68 61 6e 64 6c 65 20 74 6f 20 74 68 65 20 62 handle to the b
21b00 6c 6f 62 20 6c 6f 63 61 74 65 64 20 69 6e 20 72 lob located in r
21b10 6f 77 20 69 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e ow iRow,, column
21b20 20 7a 43 6f 6c 75 6d 6e 2c 20 0a 2a 2a 20 74 61 zColumn, .** ta
21b30 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 ble zTable in da
21b40 74 61 62 61 73 65 20 7a 44 62 2e 20 69 2e 65 2e tabase zDb. i.e.
21b50 20 74 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74 the same blob t
21b60 68 61 74 20 77 6f 75 6c 64 0a 2a 2a 20 62 65 20 hat would.** be
21b70 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a selected by:.**.
21b80 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 ** <pre>.**
21b90 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 SELECT zColumn F
21ba0 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 ROM zDb.zTable W
21bb0 48 45 52 45 20 72 6f 77 69 64 20 3d 20 69 52 6f HERE rowid = iRo
21bc0 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a w;.** </pre>.**.
21bd0 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67 73 20 ** If the flags
21be0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e parameter is non
21bf0 2d 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 -zero, the blob
21c00 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 0a 2a is opened for .*
21c10 2a 20 72 65 61 64 20 61 6e 64 20 77 72 69 74 65 * read and write
21c20 20 61 63 63 65 73 73 2e 20 49 66 20 69 74 20 69 access. If it i
21c30 73 20 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 s zero, the blob
21c40 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
21c50 65 61 64 20 0a 2a 2a 20 61 63 63 65 73 73 2e 0a ead .** access..
21c60 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 **.** On success
21c70 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 , [SQLITE_OK] is
21c80 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 returned and th
21c90 65 20 6e 65 77 20 0a 2a 2a 20 5b 73 71 6c 69 74 e new .** [sqlit
21ca0 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 e3_blob | blob h
21cb0 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65 andle] is writte
21cc0 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 0a 2a 2a n to *ppBlob..**
21cd0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 Otherwise an er
21ce0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 ror code is retu
21cf0 72 6e 65 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 rned and .** any
21d00 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 74 value written t
21d10 6f 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 o *ppBlob should
21d20 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 not be used by
21d30 74 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 the caller..** T
21d40 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 his function set
21d50 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2d 68 s the database-h
21d60 61 6e 64 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 andle error code
21d70 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 and message.**
21d80 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b accessible via [
21d90 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
21da0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
21db0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e errmsg()]..*/.in
21dc0 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f t sqlite3_blob_o
21dd0 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c pen(. sqlite3*,
21de0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
21df0 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 Db,. const char
21e00 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 *zTable,. cons
21e10 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c t char *zColumn,
21e20 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 . sqlite3_int64
21e30 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 iRow,. int fla
21e40 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c gs,. sqlite3_bl
21e50 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a ob **ppBlob.);..
21e60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
21e70 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 Close A BLOB Ha
21e80 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 ndle.**.** Close
21e90 20 61 6e 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 an open [sqlite
21ea0 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 3_blob | blob ha
21eb0 6e 64 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ndle]..*/.int sq
21ec0 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 lite3_blob_close
21ed0 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 (sqlite3_blob *)
21ee0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
21ef0 46 3a 20 20 52 65 74 75 72 6e 20 54 68 65 20 53 F: Return The S
21f00 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 ize Of An Open B
21f10 4c 4f 42 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e LOB.**.** Return
21f20 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 the size in byt
21f30 65 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 61 es of the blob a
21f40 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 ccessible via th
21f50 65 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 e open .** [sqli
21f60 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d te3_blob | blob-
21f70 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 handle] passed a
21f80 73 20 61 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a s an argument..*
21f90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c /.int sqlite3_bl
21fa0 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 ob_bytes(sqlite3
21fb0 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a _blob *);../*.**
21fc0 20 43 41 50 49 33 52 45 46 3a 20 20 52 65 61 64 CAPI3REF: Read
21fd0 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f Data From A BLO
21fe0 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a B Incrementally.
21ff0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
22000 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 ion is used to r
22010 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e ead data from an
22020 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 open .** [sqlit
22030 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 e3_blob | blob-h
22040 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 20 63 61 andle] into a ca
22050 6c 6c 65 72 20 73 75 70 70 6c 69 65 64 20 62 75 ller supplied bu
22060 66 66 65 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73 ffer..** n bytes
22070 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 of data are cop
22080 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 0a ied into buffer.
22090 2a 2a 20 7a 20 66 72 6f 6d 20 74 68 65 20 6f 70 ** z from the op
220a0 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e en blob, startin
220b0 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 g at offset iOff
220c0 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 set..**.** On su
220d0 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b ccess, SQLITE_OK
220e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 is returned. Ot
220f0 68 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20 herwise, an .**
22100 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 [SQLITE_ERROR |
22110 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64 SQLite error cod
22120 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c e] or an.** [SQL
22130 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c ITE_IOERR_READ |
22140 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 extended error
22150 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
22160 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 d..*/.int sqlite
22170 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 3_blob_read(sqli
22180 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 te3_blob *, void
22190 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 *z, int n, int
221a0 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a iOffset);../*.**
221b0 20 43 41 50 49 33 52 45 46 3a 20 20 57 72 69 74 CAPI3REF: Writ
221c0 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c e Data Into A BL
221d0 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 OB Incrementally
221e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
221f0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
22200 77 72 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20 write data into
22210 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c an open .** [sql
22220 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 ite3_blob | blob
22230 2d 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 20 -handle] from a
22240 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 62 75 user supplied bu
22250 66 66 65 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73 ffer..** n bytes
22260 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 of data are cop
22270 69 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 ied from the buf
22280 66 65 72 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 fer.** pointed t
22290 6f 20 62 79 20 7a 20 69 6e 74 6f 20 74 68 65 20 o by z into the
222a0 6f 70 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 open blob, start
222b0 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f ing at offset iO
222c0 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ffset..**.** If
222d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f the [sqlite3_blo
222e0 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d b | blob-handle]
222f0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 passed as the f
22300 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a irst argument.**
22310 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 was not opened
22320 66 6f 72 20 77 72 69 74 69 6e 67 20 28 74 68 65 for writing (the
22330 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
22340 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f to [sqlite3_blo
22350 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 2a 20 77 61 b_open()].*** wa
22360 73 20 7a 65 72 6f 29 2c 20 74 68 69 73 20 66 75 s zero), this fu
22370 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b nction returns [
22380 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d SQLITE_READONLY]
22390 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e ..**.** This fun
223a0 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d ction may only m
223b0 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e odify the conten
223c0 74 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 ts of the blob,
223d0 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 it is.** not pos
223e0 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 sible to increas
223f0 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 e the size of a
22400 62 6c 6f 62 20 75 73 69 6e 67 20 74 68 69 73 20 blob using this
22410 41 50 49 2e 20 49 66 0a 2a 2a 20 6f 66 66 73 65 API. If.** offse
22420 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 t iOffset is les
22430 73 20 74 68 61 6e 20 6e 20 62 79 74 65 73 20 66 s than n bytes f
22440 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 rom the end of t
22450 68 65 20 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51 he blob, .** [SQ
22460 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 LITE_ERROR] is r
22470 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 eturned and no d
22480 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a ata is written..
22490 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 **.** On success
224a0 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 , SQLITE_OK is r
224b0 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 eturned. Otherwi
224c0 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 se, an .** [SQLI
224d0 54 45 5f 45 52 52 4f 52 20 7c 20 53 51 4c 69 74 TE_ERROR | SQLit
224e0 65 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 e error code] or
224f0 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 an.** [SQLITE_I
22500 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 OERR_READ | exte
22510 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d nded error code]
22520 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f is returned..*/
22530 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f .int sqlite3_blo
22540 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f b_write(sqlite3_
22550 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f blob *, const vo
22560 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e id *z, int n, in
22570 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a t iOffset);../*.
22580 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 56 69 ** CAPI3REF: Vi
22590 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 rtual File Syste
225a0 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20 m Objects.**.**
225b0 41 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 A virtual filesy
225c0 73 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e stem (VFS) is an
225d0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
225e0 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 bject.** that SQ
225f0 4c 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 Lite uses to int
22600 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 eract.** with th
22610 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 e underlying ope
22620 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 rating system.
22630 4d 6f 73 74 20 62 75 69 6c 64 73 20 63 6f 6d 65 Most builds come
22640 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c with a.** singl
22650 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68 e default VFS th
22660 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 at is appropriat
22670 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63 e for the host c
22680 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 omputer..** New
22690 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67 VFSes can be reg
226a0 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73 istered and exis
226b0 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62 ting VFSes can b
226c0 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a e unregistered..
226d0 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ** The following
226e0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
226f0 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 provided..**.**
22700 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f The sqlite3_vfs_
22710 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65 find() interface
22720 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
22730 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65 er to a VFS give
22740 6e 20 69 74 73 0a 2a 2a 20 6e 61 6d 65 2e 20 20 n its.** name.
22750 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73 Names are case s
22760 65 6e 73 69 74 69 76 65 2e 20 20 49 66 20 74 68 ensitive. If th
22770 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c ere is no match,
22780 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 a NULL.** point
22790 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 er is returned.
227a0 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 If zVfsName is
227b0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 NULL then the de
227c0 66 61 75 6c 74 20 0a 2a 2a 20 56 46 53 20 69 73 fault .** VFS is
227d0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
227e0 20 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 72 New VFSes are r
227f0 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 73 egistered with s
22800 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 qlite3_vfs_regis
22810 74 65 72 28 29 2e 20 20 45 61 63 68 0a 2a 2a 20 ter(). Each.**
22820 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 new VFS becomes
22830 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 the default VFS
22840 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 if the makeDflt
22850 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 flag is set..**
22860 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e The same VFS can
22870 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d be registered m
22880 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 ultiple times wi
22890 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a thout injury..**
228a0 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 To make an exis
228b0 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 ting VFS into th
228c0 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 e default VFS, r
228d0 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e egister it again
228e0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b .** with the mak
228f0 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 0a eDflt flag set..
22900 2a 2a 20 0a 2a 2a 20 55 6e 72 65 67 69 73 74 65 ** .** Unregiste
22910 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68 65 r a VFS with the
22920 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 sqlite3_vfs_unr
22930 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 66 egister() interf
22940 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64 ace..** If the d
22950 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e efault VFS is un
22960 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74 registered, anot
22970 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 65 her VFS is chose
22980 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 n as.** the defa
22990 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65 ult. The choice
229a0 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53 for the new VFS
229b0 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a is arbitrary..*
229c0 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 /.sqlite3_vfs *s
229d0 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 qlite3_vfs_find(
229e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 const char *zVfs
229f0 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 Name);.int sqlit
22a00 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 e3_vfs_register(
22a10 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
22a20 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 t makeDflt);.int
22a30 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 sqlite3_vfs_unr
22a40 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f egister(sqlite3_
22a50 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 vfs*);../*.** CA
22a60 50 49 33 52 45 46 3a 20 4d 75 74 65 78 65 73 0a PI3REF: Mutexes.
22a70 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 **.** The SQLite
22a80 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 core uses these
22a90 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 routines for th
22aa0 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e read.** synchron
22ab0 69 7a 61 74 69 6f 6e 2e 20 20 54 68 6f 75 67 68 ization. Though
22ac0 20 74 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64 they are intend
22ad0 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a ed for internal.
22ae0 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 ** use by SQLite
22af0 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b , code that link
22b00 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 s against SQLite
22b10 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 is.** permitted
22b20 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74 to use any of t
22b30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a hese routines..*
22b40 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 *.** The SQLite
22b50 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 source code cont
22b60 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d ains multiple im
22b70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 0a 2a plementations .*
22b80 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65 78 * of these mutex
22b90 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 routines. An a
22ba0 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 ppropriate imple
22bb0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 mentation.** is
22bc0 73 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61 74 selected automat
22bd0 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c ically at compil
22be0 65 2d 74 69 6d 65 2e 20 20 54 68 65 20 66 6f 6c e-time. The fol
22bf0 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d lowing.** implem
22c00 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 61 76 entations are av
22c10 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 53 ailable in the S
22c20 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a QLite core:.**.*
22c30 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 * <ul>.** <li>
22c40 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 SQLITE_MUTEX_PT
22c50 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 HREAD.** <li>
22c60 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 49 4e SQLITE_MUTEX_WIN
22c70 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 .** <li> SQLIT
22c80 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 E_MUTEX_NOOP.**
22c90 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 </ul>.**.** The
22ca0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f SQLITE_MUTEX_NOO
22cb0 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e P implementation
22cc0 20 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f 75 is a set of rou
22cd0 74 69 6e 65 73 20 0a 2a 2a 20 74 68 61 74 20 64 tines .** that d
22ce0 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b oes no real lock
22cf0 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f ing and is appro
22d00 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 69 priate for use i
22d10 6e 20 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 n .** a single-t
22d20 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 hreaded applicat
22d30 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 54 45 ion. The SQLITE
22d40 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a _MUTEX_PTHREAD.*
22d50 2a 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 * and SQLITE_MUT
22d60 45 58 5f 57 49 4e 20 69 6d 70 6c 65 6d 65 6e 74 EX_WIN implement
22d70 61 74 69 6f 6e 73 20 61 72 65 20 61 70 70 72 6f ations are appro
22d80 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 75 73 priate for.** us
22d90 65 20 6f 6e 20 75 6e 69 78 20 61 6e 64 20 77 69 e on unix and wi
22da0 6e 64 6f 77 73 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 ndows..** .** If
22db0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
22dc0 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c led with the SQL
22dd0 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 ITE_MUTEX_APPDEF
22de0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a preprocessor.**
22df0 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 macro defined (
22e00 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d with "-DSQLITE_M
22e10 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c UTEX_APPDEF=1"),
22e20 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a then no mutex.*
22e30 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
22e40 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 is included wit
22e50 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 20 h the library.
22e60 54 68 65 0a 2a 2a 20 6d 75 74 65 78 20 69 6e 74 The.** mutex int
22e70 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 erface routines
22e80 64 65 66 69 6e 65 64 20 68 65 72 65 20 62 65 63 defined here bec
22e90 6f 6d 65 20 65 78 74 65 72 6e 61 6c 0a 2a 2a 20 ome external.**
22ea0 72 65 66 65 72 65 6e 63 65 73 20 69 6e 20 74 68 references in th
22eb0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
22ec0 20 66 6f 72 20 77 68 69 63 68 20 69 6d 70 6c 65 for which imple
22ed0 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6d 75 mentations.** mu
22ee0 73 74 20 62 65 20 70 72 6f 76 69 64 65 64 20 62 st be provided b
22ef0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
22f00 6e 2e 20 20 54 68 69 73 20 66 61 63 69 6c 69 74 n. This facilit
22f10 79 20 61 6c 6c 6f 77 73 20 61 6e 0a 2a 2a 20 61 y allows an.** a
22f20 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 pplication that
22f30 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 links against SQ
22f40 4c 69 74 65 20 74 6f 20 70 72 6f 76 69 64 65 20 Lite to provide
22f50 69 74 73 20 6f 77 6e 20 6d 75 74 65 78 0a 2a 2a its own mutex.**
22f60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
22f70 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 without having t
22f80 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c o modify the SQL
22f90 69 74 65 20 63 6f 72 65 2e 0a 2a 2a 0a 2a 2a 20 ite core..**.**
22fa0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 The sqlite3_mute
22fb0 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e x_alloc() routin
22fc0 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 e allocates a ne
22fd0 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 w.** mutex and r
22fe0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
22ff0 20 74 6f 20 69 74 2e 20 20 49 66 20 69 74 20 72 to it. If it r
23000 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 eturns NULL.** t
23010 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61 hat means that a
23020 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 mutex could not
23030 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 be allocated.
23040 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 SQLite.** will u
23050 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 nwind its stack
23060 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 and return an er
23070 72 6f 72 2e 20 20 54 68 65 20 61 72 67 75 6d 65 ror. The argume
23080 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 nt.** to sqlite3
23090 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 _mutex_alloc() i
230a0 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 s one of these i
230b0 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
230c0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
230d0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 <li> SQLITE_MUT
230e0 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 EX_FAST.** <li>
230f0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 SQLITE_MUTEX_RE
23100 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 CURSIVE.** <li>
23110 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
23120 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c ATIC_MASTER.** <
23130 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 li> SQLITE_MUTE
23140 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 X_STATIC_MEM.**
23150 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 <li> SQLITE_MUT
23160 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a EX_STATIC_MEM2.*
23170 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d * <li> SQLITE_M
23180 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 UTEX_STATIC_PRNG
23190 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
231a0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 _MUTEX_STATIC_LR
231b0 55 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a U.** </ul>.**.**
231c0 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63 The first two c
231d0 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20 73 onstants cause s
231e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
231f0 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a oc() to create.*
23200 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 * a new mutex.
23210 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73 The new mutex is
23220 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20 recursive when
23230 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 SQLITE_MUTEX_REC
23240 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 URSIVE.** is use
23250 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 d but not necess
23260 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 arily so when SQ
23270 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 LITE_MUTEX_FAST
23280 69 73 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65 20 is used..** The
23290 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 mutex implementa
232a0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 tion does not ne
232b0 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 ed to make a dis
232c0 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 tinction.** betw
232d0 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 een SQLITE_MUTEX
232e0 5f 52 45 43 55 52 53 49 56 45 20 61 6e 64 20 53 _RECURSIVE and S
232f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 QLITE_MUTEX_FAST
23300 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e if it does.** n
23310 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 42 75 74 ot want to. But
23320 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c SQLite will onl
23330 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75 y request a recu
23340 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a rsive mutex in.*
23350 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74 * cases where it
23360 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e really needs on
23370 65 2e 20 20 49 66 20 61 20 66 61 73 74 65 72 20 e. If a faster
23380 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d 75 non-recursive mu
23390 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 tex.** implement
233a0 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 ation is availab
233b0 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20 70 le on the host p
233c0 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74 latform, the mut
233d0 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 ex subsystem.**
233e0 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 75 63 might return suc
233f0 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65 73 h a mutex in res
23400 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45 5f ponse to SQLITE_
23410 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a MUTEX_FAST..**.*
23420 2a 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f * The other allo
23430 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 wed parameters t
23440 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f o sqlite3_mutex_
23450 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74 alloc() each ret
23460 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 urn.** a pointer
23470 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 to a static pre
23480 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 existing mutex.
23490 20 46 6f 75 72 20 73 74 61 74 69 63 20 6d 75 74 Four static mut
234a0 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 exes are.** used
234b0 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 by the current
234c0 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 version of SQLit
234d0 65 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 e. Future versi
234e0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a ons of SQLite.**
234f0 20 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 6f may add additio
23500 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 nal static mutex
23510 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65 es. Static mute
23520 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65 xes are for inte
23530 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 rnal.** use by S
23540 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 QLite only. App
23550 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 lications that u
23560 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65 se SQLite mutexe
23570 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 s should.** use
23580 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63 only the dynamic
23590 20 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e 65 mutexes returne
235a0 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 d by SQLITE_MUTE
235b0 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c X_FAST or.** SQL
235c0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 ITE_MUTEX_RECURS
235d0 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 IVE..**.** Note
235e0 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 that if one of t
235f0 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 he dynamic mutex
23600 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c parameters (SQL
23610 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a ITE_MUTEX_FAST.*
23620 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 * or SQLITE_MUTE
23630 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20 X_RECURSIVE) is
23640 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 used then sqlite
23650 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 3_mutex_alloc().
23660 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 ** returns a dif
23670 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 ferent mutex on
23680 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 42 75 74 every call. But
23690 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 20 for the static
236a0 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c .** mutex types,
236b0 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 the same mutex
236c0 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 is returned on e
236d0 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 very call that h
236e0 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 as.** the same t
236f0 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a ype number..**.*
23700 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 * The sqlite3_mu
23710 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 tex_free() routi
23720 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 ne deallocates a
23730 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 previously.** a
23740 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 llocated dynamic
23750 20 6d 75 74 65 78 2e 20 20 53 51 4c 69 74 65 20 mutex. SQLite
23760 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65 is careful to de
23770 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a allocate every.*
23780 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 * dynamic mutex
23790 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 that it allocate
237a0 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63 20 s. The dynamic
237b0 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 mutexes must not
237c0 20 62 65 20 69 6e 20 0a 2a 2a 20 75 73 65 20 77 be in .** use w
237d0 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 hen they are dea
237e0 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d llocated. Attem
237f0 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 pting to dealloc
23800 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 ate a static.**
23810 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e mutex results in
23820 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
23830 69 6f 72 2e 20 20 53 51 4c 69 74 65 20 6e 65 76 ior. SQLite nev
23840 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a er deallocates.*
23850 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 * a static mutex
23860 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
23870 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 te3_mutex_enter(
23880 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 ) and sqlite3_mu
23890 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e tex_try() routin
238a0 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f es attempt.** to
238b0 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20 enter a mutex.
238c0 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 If another thre
238d0 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 69 ad is already wi
238e0 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a thin the mutex,.
238f0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ** sqlite3_mutex
23900 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c _enter() will bl
23910 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f ock and sqlite3_
23920 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c mutex_try() will
23930 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 return.** SQLIT
23940 45 5f 42 55 53 59 2e 20 20 54 68 65 20 73 71 6c E_BUSY. The sql
23950 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 ite3_mutex_try()
23960 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
23970 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a 20 ns SQLITE_OK.**
23980 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c 20 upon successful
23990 65 6e 74 72 79 2e 20 20 4d 75 74 65 78 65 73 20 entry. Mutexes
239a0 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 53 51 created using SQ
239b0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
239c0 53 49 56 45 20 63 61 6e 0a 2a 2a 20 62 65 20 65 SIVE can.** be e
239d0 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 ntered multiple
239e0 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d times by the sam
239f0 65 20 74 68 72 65 61 64 2e 20 20 49 6e 20 73 75 e thread. In su
23a00 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a ch cases the,.**
23a10 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 mutex must be e
23a20 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e xited an equal n
23a30 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 umber of times b
23a40 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 efore another th
23a50 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 read.** can ente
23a60 72 2e 20 20 49 66 20 74 68 65 20 73 61 6d 65 20 r. If the same
23a70 74 68 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 thread tries to
23a80 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72 20 enter any other
23a90 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 0a 2a 2a kind of mutex.**
23aa0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c more than once,
23ab0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
23ac0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 20 53 51 undefined. SQ
23ad0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 Lite will never
23ae0 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 exhibit.** such
23af0 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 behavior in its
23b00 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 own use of mutex
23b10 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 es..**.** The sq
23b20 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 lite3_mutex_leav
23b30 65 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69 74 e() routine exit
23b40 73 20 61 20 6d 75 74 65 78 20 74 68 61 74 20 77 s a mutex that w
23b50 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 as.** previously
23b60 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 20 entered by the
23b70 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20 54 68 same thread. Th
23b80 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 e behavior.** is
23b90 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 undefined if th
23ba0 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 e mutex is not c
23bb0 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 urrently entered
23bc0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 by the.** calli
23bd0 6e 67 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 ng thread or is
23be0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c not currently al
23bf0 6c 6f 63 61 74 65 64 2e 20 20 53 51 4c 69 74 65 located. SQLite
23c00 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 will.** never d
23c10 6f 20 65 69 74 68 65 72 2e 0a 2a 2a 0a 2a 2a 20 o either..**.**
23c20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
23c30 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d e3_mutex_held()]
23c40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 and [sqlite3_mu
23c50 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a tex_notheld()]..
23c60 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 */.sqlite3_mutex
23c70 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f *sqlite3_mutex_
23c80 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 alloc(int);.void
23c90 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 sqlite3_mutex_f
23ca0 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 ree(sqlite3_mute
23cb0 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 x*);.void sqlite
23cc0 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71 3_mutex_enter(sq
23cd0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 lite3_mutex*);.i
23ce0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 nt sqlite3_mutex
23cf0 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 _try(sqlite3_mut
23d00 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 ex*);.void sqlit
23d10 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 e3_mutex_leave(s
23d20 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a qlite3_mutex*);.
23d30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
23d40 20 4d 75 74 65 78 20 56 65 72 69 66 63 61 74 69 Mutex Verifcati
23d50 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a on Routines.**.*
23d60 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 * The sqlite3_mu
23d70 74 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 tex_held() and s
23d80 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 qlite3_mutex_not
23d90 68 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a held() routines.
23da0 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 ** are intended
23db0 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 for use inside a
23dc0 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e ssert() statemen
23dd0 74 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 ts. The SQLite
23de0 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73 core.** never us
23df0 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 es these routine
23e00 73 20 65 78 63 65 70 74 20 69 6e 73 69 64 65 20 s except inside
23e10 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e 64 20 an assert() and
23e20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
23e30 61 72 65 20 61 64 76 69 73 65 64 20 74 6f 20 66 are advised to f
23e40 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 20 6f ollow the lead o
23e50 66 20 74 68 65 20 63 6f 72 65 2e 20 20 54 68 65 f the core. The
23e60 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 core only.** pr
23e70 6f 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 ovides implement
23e80 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 ations for these
23e90 20 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 routines when i
23ea0 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a t is compiled.**
23eb0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 with the SQLITE
23ec0 5f 44 45 42 55 47 20 66 6c 61 67 2e 20 20 45 78 _DEBUG flag. Ex
23ed0 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 ternal mutex imp
23ee0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 lementations.**
23ef0 61 72 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 are only require
23f00 64 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65 d to provide the
23f10 73 65 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53 se routines if S
23f20 51 4c 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a QLITE_DEBUG is.*
23f30 2a 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66 * defined and if
23f40 20 4e 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64 NDEBUG is not d
23f50 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 efined..**.** Th
23f60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f ese routines sho
23f70 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 uld return true
23f80 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 if the mutex in
23f90 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a their argument.*
23fa0 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 * is held or not
23fb0 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 held, respectiv
23fc0 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c ely, by the call
23fd0 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a ing thread..**.*
23fe0 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 * The implementa
23ff0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 tion is not requ
24000 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 ired to provided
24010 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 versions of the
24020 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 se.** routines t
24030 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 hat actually wor
24040 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6d 70 k..** If the imp
24050 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 lementation does
24060 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 77 6f 72 not provide wor
24070 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 king.** versions
24080 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
24090 65 73 2c 20 69 74 20 73 68 6f 75 6c 64 20 61 74 es, it should at
240a0 20 6c 65 61 73 74 20 70 72 6f 76 69 64 65 20 73 least provide s
240b0 74 75 62 73 0a 2a 2a 20 74 68 61 74 20 61 6c 77 tubs.** that alw
240c0 61 79 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 ays return true
240d0 73 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 so that one does
240e0 20 6e 6f 74 20 67 65 74 20 73 70 75 72 69 6f 75 not get spuriou
240f0 73 0a 2a 2a 20 61 73 73 65 72 74 69 6f 6e 20 66 s.** assertion f
24100 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 ailures..**.** I
24110 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 f the argument t
24120 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f o sqlite3_mutex_
24130 68 65 6c 64 28 29 20 69 73 20 61 20 4e 55 4c 4c held() is a NULL
24140 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a pointer then.**
24150 20 74 68 65 20 72 6f 75 74 69 6e 65 20 73 68 6f the routine sho
24160 75 6c 64 20 72 65 74 75 72 6e 20 31 2e 20 20 54 uld return 1. T
24170 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 his seems counte
24180 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 r-intuitive sinc
24190 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 e.** clearly the
241a0 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 mutex cannot be
241b0 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 held if it does
241c0 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 not exist. But
241d0 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 the.** the reas
241e0 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65 on the mutex doe
241f0 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62 s not exist is b
24200 65 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 64 ecause the build
24210 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 is not.** using
24220 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77 mutexes. And w
24230 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 e do not want th
24240 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61 e assert() conta
24250 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c ining the.** cal
24260 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 l to sqlite3_mut
24270 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69 ex_held() to fai
24280 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f l, so a non-zero
24290 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 return is.** th
242a0 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 68 e appropriate th
242b0 69 6e 67 20 74 6f 20 64 6f 2e 20 20 54 68 65 20 ing to do. The
242c0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f sqlite3_mutex_no
242d0 74 68 65 6c 64 28 29 20 0a 2a 2a 20 69 6e 74 65 theld() .** inte
242e0 72 66 61 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 rface should als
242f0 6f 20 72 65 74 75 72 6e 20 31 20 77 68 65 6e 20 o return 1 when
24300 67 69 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 given a NULL poi
24310 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c nter..*/.int sql
24320 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 ite3_mutex_held(
24330 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b sqlite3_mutex*);
24340 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 .int sqlite3_mut
24350 65 78 5f 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74 ex_notheld(sqlit
24360 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a e3_mutex*);../*.
24370 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 ** CAPI3REF: Mut
24380 65 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 54 ex Types.**.** T
24390 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
243a0 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 x_alloc()] inter
243b0 66 61 63 65 20 74 61 6b 65 73 20 61 20 73 69 6e face takes a sin
243c0 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 gle argument.**
243d0 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 which is one of
243e0 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f these integer co
243f0 6e 73 74 61 6e 74 73 2e 0a 2a 2f 0a 23 64 65 66 nstants..*/.#def
24400 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 ine SQLITE_MUTEX
24410 5f 46 41 53 54 20 20 20 20 20 20 20 20 20 20 20 _FAST
24420 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
24430 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 TE_MUTEX_RECURSI
24440 56 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 VE 1.#def
24450 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 ine SQLITE_MUTEX
24460 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 20 20 _STATIC_MASTER
24470 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
24480 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
24490 4d 45 4d 20 20 20 20 20 20 20 33 20 20 2f 2a 20 MEM 3 /*
244a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
244b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
244c0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
244d0 4d 45 4d 32 20 20 20 20 20 20 34 20 20 2f 2a 20 MEM2 4 /*
244e0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f sqlite3_release_
244f0 6d 65 6d 6f 72 79 28 29 20 2a 2f 0a 23 64 65 66 memory() */.#def
24500 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 ine SQLITE_MUTEX
24510 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 20 20 20 _STATIC_PRNG
24520 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 5 /* sqlite3_
24530 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 random() */.#def
24540 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 ine SQLITE_MUTEX
24550 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 20 20 20 _STATIC_LRU
24560 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 6 /* lru page
24570 20 6c 69 73 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a list */.../*.**
24580 20 55 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 74 Undo the hack t
24590 68 61 74 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f hat converts flo
245a0 61 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 65 ating point type
245b0 73 20 74 6f 20 69 6e 74 65 67 65 72 20 66 6f 72 s to integer for
245c0 0a 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 72 .** builds on pr
245d0 6f 63 65 73 73 6f 72 73 20 77 69 74 68 6f 75 74 ocessors without
245e0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
245f0 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64 support..*/.#ifd
24600 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 ef SQLITE_OMIT_F
24610 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 LOATING_POINT.#
24620 75 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e undef double.#en
24630 64 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70 dif..#ifdef __cp
24640 6c 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e lusplus.} /* En
24650 64 20 6f 66 20 74 68 65 20 27 65 78 74 65 72 6e d of the 'extern
24660 20 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23 "C"' block */.#
24670 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a endif.#endif.